1 \documentstyle[12pt,fullpage,changebar]{article}
5 \setlength{\parskip}{.7\baselineskip}
6 \setlength{\parindent}{0pt}
11 \title{OV*Secure Admin \\ Functional Specifications}
13 \date{DRAFT --- \today}
15 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
16 %% Make _ actually generate an _, and allow line-breaking after it.
19 \def_{\underscore\penalty75\relax}
20 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26 {\setlength{\parskip}{0pt}\tableofcontents}
28 \section{Policies and Password Quality}
30 The Admin API Password Quality mechanism provides the following
31 controls. Note that two strings are defined to be ``significantly
32 different'' if they differ by at least two characters.
35 \item A minimum length can be required; a password with
36 fewer than the specified number of characters will not be accepted.
38 \item A minimum number of character classes can be required; a
39 password that does not contain at least one character from at least
40 the specified number of character classes will not be accepted. The
41 character classes are defined by islower(), isupper(), isdigit(),
44 \item Passwords can be required to be different from
45 previous passwords; a password that generates the same encryption key
46 as any of the principal's specified previous number of passwords will
47 not be accepted. This comparison is performed on the encryption keys
48 generated from the passwords, not on the passwords themselves.
50 \item A single ``forbidden password'' dictionary can be specified for all
51 users; a password that is not significantly different from every word
52 in the dictionary will not be accepted.
54 \item A password that is not significantly different from each
55 component and the realm of the principal's name will not be accepted.
58 \section{Interrealm Operation}
60 For version 1.0, the behavior of any function when called with a
61 principal name that is not in the host's local realm is undefined.
65 This section describes the Admin API that can be used to maintain
66 principals and policies. It describes the data structures used for
67 each function and the interpretation of each data type field, the
68 semantics of each API function, and the possible return codes.
70 The Admin API is intended to be used by remote clients using an RPC
71 interface. It is implemented by the admin server running on the
72 Kerberos master server. It may also be possible for a program running
73 on the Kerberos master server to use the Admin API directly, without
74 going through the admin server.
76 \subsection{Data Structures}
78 This section describes the data structures used by the Admin API that
79 are unique to \secure{}. They are defined in $<$ovsec_admin/admin.h$>$.
81 \subsubsection{Principals, ovsec_kadm_principal_ent_t}
82 \label{sec:principal-structure}
84 A Kerberos principal entry is represented by a
85 ovsec_kadm_principal_ent_t. It contains a subset of the information
86 stored in the master Kerberos database as well as the additional
87 information maintained by \secure{}. In the current version, the only
88 additional information is the principal's policy and the
91 The principal may or may not have a policy enforced on it. If the
92 POLICY bit (see section \ref{sec:masks}) is set in aux_attributes, the
93 policy field names the principal's policy. If the POLICY bit is not
94 set in aux_attributes, no policy is enforced on the principal and the
95 value of the policy field is undefined.
99 typedef struct _ovsec_kadm_principal_ent_t {
100 krb5_principal principal;
102 krb5_timestamp princ_expire_time;
103 krb5_timestamp last_pwd_change;
104 krb5_timestamp pw_expiration;
105 krb5_deltat max_life;
106 krb5_principal mod_name;
107 krb5_timestamp mod_date;
108 krb5_flags attributes;
113 u_int32 aux_attributes;
114 } ovsec_kadm_principal_ent_rec, *ovsec_kadm_principal_ent_t;
116 \caption{Definition of ovsec_kadm_principal_ent_t.}
120 The fields of an ovsec_kadm_principal_ent_t are interpreted as
124 \item[principal] The name of the principal; must conform to Kerberos
125 naming specifications.
127 \item[princ_expire_time] The expire time of the principal as a Kerberos
128 timestamp. No Kerberos tickets will be issued for a principal after
131 \item[last_pwd_change] The time this principal's password was last
132 changed, as a Kerberos timestamp.
134 \item[pw_expiration] The expire time of the user's current password, as a
135 Kerberos timestamp. No application service tickets will be issued for the
136 principal once the password expire time has passed. Note that the
137 user can still obtain ticket-granting tickets.
139 \item[max_life] The maximum lifetime of any Kerberos ticket issued to
142 \item[attributes] A bitfield of attributes for use by the KDC.
143 Note that only some are explicitly supported by \secure{}.
146 {\bf Supported} & {\bf Name} & {\bf Value} \\
147 & KRB5_KDB_DISALLOW_POSTDATED & 0x00000001 \\
148 & KRB5_KDB_DISALLOW_FORWARDABLE & 0x00000002 \\
149 X & KRB5_KDB_DISALLOW_TGT_BASED & 0x00000004 \\
150 & KRB5_KDB_DISALLOW_RENEWABLE & 0x00000008 \\
151 & KRB5_KDB_DISALLOW_PROXIABLE & 0x00000010 \\
152 & KRB5_KDB_DISALLOW_DUP_SKEY & 0x00000020 \\
153 X & KRB5_KDB_DISALLOW_ALL_TIX & 0x00000040 \\
154 & KRB5_KDB_REQUIRES_PRE_AUTH & 0x00000080 \\
155 & KRB5_KDB_REQUIRES_HW_AUTH & 0x00000100 \\
156 X & KRB5_KDB_REQUIRES_PWCHANGE & 0x00000200 \\
157 & KRB5_KDB_DISALLOW_SVR & 0x00001000 \\
158 X & KRB5_KDB_PWCHANGE_SERVICE & 0x00002000
161 The interpretation of each bit is as follows. For each of the bits
162 that disables a corresponding KDC_OPT option, the option is disabled
163 on an AS_REQ if the bit is set on either the client or the server, and
164 the option is disabled on TGS_REQ if the bit is set on the server (the
165 setting of the bit on the client is irrelevant for a TGS_REQ).
168 \item[KRB5_KDB_DISALLOW_POSTDATED] Disables the ALLOW_POSTDATE
169 and POSTDATED KDC options on AS_REQ and TGS_REQ.
171 \item[KRB5_KDB_DISALLOW_FORWARDABLE] Disables the FORWARDABLE KDC
172 option for AS_REQ and TGS_REQ.
174 \item[KRB5_KDB_DISALLOW_TGT_BASED] All TGS_REQ requests will fail for
175 a principal with this bit set.
177 \item[KRB5_KDB_DISALLOW_RENEWABLE] Disables the RENEWABLE KDC option for
180 \item[KRB5_KDB_DISALLOW_PROXIABLE] Disables the PROXIABLE KDC option on
183 \item[KRB5_KDB_DISALLOW_DUP_SKEY] Disables the ENC_TKT_IN_SKEY option on
186 \item[KRB5_KDB_DISALLOW_ALL_TIX] All AS_REQ requests fail if this bit
187 is set for the client or the server, and all TGS_REQ requests fail if
188 this bit is set for the server. Note that this bit can be set
189 automatically if the symbol KRBCONF_KDC_MODIFIES_KDC is defined and a
190 specified number of pre-authentication attempts fail.
192 \item[KRB5_KDB_REQUIRES_PRE_AUTH] Any AS_REQ will fail if this bit is
193 set and the padata field of the request is empty. Any TGS_REQ will
194 fail if this bit is set and the TKT_FLAG_PRE_AUTH bit is not set in
195 the tgt. Thus, it is possible to have the bit not set on the TGT but
196 to have a specific service require pre-authentication.
198 \item[KRB5_KDB_REQUIRES_HW_AUTH] Unclear.
200 \item[KRB5_KDB_REQUIRES_PWCHANGE] An AS_REQ will fail if this bit is
201 set on the client and the KRB5_KDC_PWCHANGE_SERVICE bit is not set on
204 \item[KRB5_KDB_DISALLOW_SVR] All AS_REQ and TGS_REQ request will fail
205 if the server has this bit set.
207 \item[KRB5_KDB_PWCHANGE_SERVICE] An request from a client whose
208 password has expired will succeed if this bit is set on the server.
209 Also see KRB5_KDC_REQUIRES_PWCHANGE.
212 \item[mod_name] The name of the Kerberos principal that most recently
213 modified this principal.
215 \item[mod_date] The time this principal was last modified, as a Kerberos
218 \item[kvno] The version of the principal's current key.
220 \item[mkvno] The version of the Kerberos Master Key in effect when
221 this principal's key was last changed.
223 \item[policy] If the POLICY bit is set in aux_attributes, the name
224 of the policy controlling this principal.
226 \item[aux_attributes] A bitfield of flags for use by the
227 administration system. Currently, the only valid flag is POLICY, and
228 it indicates whether or not the principal has a policy enforced on it.
231 \subsubsection{Policies, ovsec_kadm_policy_ent_t}
232 \label{sec:policy-fields}
234 If the POLICY bit is set in aux_attributes, the \v{policy} name field
235 in the ovsec_kadm_principal_ent_t structure refers to a password
236 policy entry defined in a \v{ovsec_kadm_policy_ent_t}.
239 typedef struct _ovsec_kadm_policy_ent_t {
244 u_int32 pw_min_length;
245 u_int32 pw_min_classes;
246 u_int32 pw_history_num;
247 u_int32 policy_refcnt;
248 } ovsec_kadm_policy_ent_rec, *ovsec_kadm_policy_ent_t;
251 The fields of an ovsec_kadm_policy_ent_t are interpreted as follows.
252 Note that a policy's values only apply to a principal using that
256 \item[policy] The name of this policy, as a NULL-terminated string.
257 The ASCII characters between 32 (space) and 126 (tilde), inclusive,
260 \item[pw_min_life] The minimum password lifetime, in seconds.
261 A principal cannot change its password before pw_min_life seconds have
262 passed since last_pwd_change.
264 \item[pw_max_life] The default duration, in seconds, used to compute
265 pw_expiration when a principal's password is changed.
267 \item[pw_min_length] The minimum password length, in characters. A
268 principal cannot set its password to anything with fewer than this
269 number of characters. This value must be greater than zero.
271 \item[pw_min_classes] The minimum number of character classes in the
272 password. This value can only be 1, 2, 3, 4, or 5. A principal cannot
273 set its password to anything with fewer than this number of character
276 \item[pw_history_num] The number of past passwords that are
277 stored for the principal; the minimum value is 1 and the maximum value
278 is 10. A principal cannot set its password to any of its previous
279 pw_history_num passwords. The first ``previous'' password is the
280 current password; thus, a principal with a policy can never reset its
281 password to its current value.
283 \item[policy_refcnt] The number of principals currently using this policy.
284 A policy cannot be deleted unless this number is zero.
287 \subsubsection{Create/Modify Masks}
290 The API functions for creating and modifying principals and policies
291 allow for a relevant subset of the fields of the
292 ovsec_kadm_principal_ent_t and ovsec_kadm_policy_ent_t to be specified
293 or changed. The chosen fields are determined by a bitmask that is
294 passed to the relevant function. Each API function has different
295 rules for which mask values can be specified, and can specify whether
296 a given mask value is mandatory, optional, or forbidden. Mandatory
297 fields must be present and forbidden fields must not be present or an
298 error is generated. When creating a principal or policy, optional
299 fields have a default value if they are not specified; when modifying
300 a principal or policy, optional fields are unchanged if they are not
301 specified. The values for forbidden fields are defined in the
304 The masks for principals are in table \ref{tab:princ-bits} and the
305 masks for policies are in table \ref{tab:policy-bits}. They are
306 defined in $<$ovsec_admin/admin.h$>$. The
307 OVSEC_KADM_ prefix has been removed from the Name fields. In the
308 Create and Modify fields, M means mandatory, F means forbidden, and O
309 means optional. Create fields that are optional specify the default
310 value. The notation ``K/M value'' means that the field inherits its
311 value from the corresponding field in the Kerberos master principal.
313 Note that the POLICY and POLICY_CLR bits are special. When POLICY is
314 set, the policy is assigned to the principal. When POLICY_CLR is
315 specified, the policy is unassigned to the principal and as a result
316 no policy controls the principal.
318 If the principal has a policy assigned, the POLICY bit is set in
322 \begin{tabular}{@{}lclll}
323 {\bf Name} & {\bf Value} & {\bf Field Affected} & {\bf Create} &
325 PRINCIPAL & 0x000001 & principal & M & F \\
326 PRINC_EXPIRE_TIME & 0x000002 & princ_expire_time & O, K/M value & O \\
327 PW_EXPIRATION & 0x000004 & pw_expiration & O, now+pw_max_life & O \\
328 LAST_PWD_CHANGE & 0x000008 & last_pwd_change & F & F \\
329 ATTRIBUTES & 0x000010 & attributes & O, 0 & O \\
330 MAX_LIFE & 0x000020 & max_life & O, K/M value & O \\
331 MOD_TIME & 0x000040 & mod_date & F & F \\
332 MOD_NAME & 0x000080 & mod_name & F & F \\
333 KVNO & 0x000100 & kvno & O, 1 & O \\
334 MKVNO & 0x000200 & mkvno & F & F \\
335 AUX_ATTRIBUTES & 0x000400 & aux_attributes & F & F \\
336 POLICY & 0x000800 & policy & O, none & O \\
337 POLICY_CLR & 0x001000 & policy & F & O
339 \caption{Mask bits for creating/modifying principals.}
340 \label{tab:princ-bits}
344 \begin{tabular}{@{}lclll}
345 Name & Value & Field Affected & Create & Modify \\
346 POLICY & same & policy & M & F \\
347 PW_MAX_LIFE & 0x004000 & pw_max_life & O, 0 (infinite) & O \\
348 PW_MIN_LIFE & 0x008000 & pw_min_life & O, 0 & O \\
349 PW_MIN_LENGTH & 0x010000 & pw_min_length & O, 1 & O \\
350 PW_MIN_CLASSES & 0x020000 & pw_min_classes & O, 1 & O \\
351 PW_HISTORY_NUM & 0x040000 & pw_history_num & O, 0 & O \\
352 REF_COUNT & 0x080000 & pw_refcnt & O, 0 & O
354 \caption{Mask bits for creating/modifying policies.}
355 \label{tab:policy-bits}
358 \subsection{Constants, Header Files, Libraries}
360 For release 1.0 both all of the files decribed in this section are
361 rooted off of the ``stage'' directory in the build tree. If we export
362 this interface in future releases they will move to the ``install''
363 tree. Include files are found under ``stage/include'', libraries under
366 $<$ovsec_admin/admin.h$>$ contains ovsec_kadm routine prototypes, data
367 structures, mask bitfields defines, and the following name and
368 location definitions:
371 \item[admin service principal] ADM_PRINCIPAL (``ovsec_kadm/admin'')
372 \item[admin history key] HIST_PRINCIPAL (``ovsec_kadm/history'')
373 \item[change password principal] CHANGEPW_PRINCIPAL (``ovsec_kadm/changepw'')
374 \item[server acl file path] ACLFILE (``/krb5/ovsec_admin.acl'')
375 \item[dictionary] WORDFILE (``/krb5/ovsec_adm_dict'')
378 OVSEC_KADM errors are described in $<$ovsec_admin/kadm_err.h$>$.
380 The location of the admin policy and principal databases are defined
381 in $<$ovsec_admin/adb.h$>$:
384 \item[admin policy database] POLICY_DB (``/krb5/ovsec_policy.db'')
385 \item[admin principal database] PRINCIPAL_DB (``/krb5/ovsec_principal.db'')
388 Client applications will link against libclient.a and server programs
389 against libsrv.a. Right now both clients and servers also need to link
390 against libcommon.a but we should put that in both libclient.a and
391 libsrv.a to simplify the linking process.
393 \subsection{Error Codes}
395 The error codes that can be returned by admin functions are listed
396 below. Error codes indicated with a ``*'' can be returned by every
397 admin function and always have the same meaning; these codes are
398 omitted from the list presented with each function.
400 The admin system guarantees that a function that returns an error code
401 has no other side effect.
403 The Admin system will use \v{com_err} for error codes. Note that this
404 means \v{com_err} codes may returned from functions that the admin
405 routines call (e.g. the kerberos library). Callers should not expect
406 that only OVSEC errors will be returned. The Admin system error code
407 table name will be ``ovk'', and the offsets will be the same as the
408 order presented here. The error table include file will be
409 $<$ovsec_admin/kadm_err.h$>$.
412 \item[* OVSEC_KADM_FAILURE] Operation failed for unspecified reason.
413 \item[* OVSEC_KADM_AUTH_GET] Operation requires ``get'' privilege.
414 \item[* OVSEC_KADM_AUTH_ADD] Operation requires ``add'' privilege.
415 \item[* OVSEC_KADM_AUTH_MODIFY] Operation requires ``modify'' privilege.
416 \item[* OVSEC_KADM_AUTH_DELETE] Operation requires ``delete'' privilege.
417 \item[* OVSEC_KADM_AUTH_INSUFFICIENT] Insufficient authorization for
419 \item[* OVSEC_KADM_BAD_DB] Database inconsistency detected.
420 \item[OVSEC_KADM_DUP] Principal or policy already exists.
421 \item[OVSEC_KADM_RPC_ERROR] Communication failure with server.
422 \item[OVSEC_KADM_NO_SRV] No administration server found for realm.
423 \item[OVSEC_KADM_BAD_HIST_KEY] Password history principal key version
425 \item[OVSEC_KADM_NOT_INIT] Connection to server not initialized.
426 \item[OVSEC_KADM_UNK_PRINC] Principal does not exist.
427 \item[OVSEC_KADM_UNK_POLICY] Policy does not exist.
428 \item[OVSEC_KADM_BAD_MASK] Invalid field mask for operation.
429 \item[OVSEC_KADM_BAD_CLASS] Invalid number of character classes.
430 \item[OVSEC_KADM_BAD_LENGTH] Invalid password length.
431 \item[OVSEC_KADM_BAD_POLICY] Illegal policy name.
432 \item[OVSEC_KADM_BAD_PRINCIPAL] Illegal principal name. XXX use krb5
434 \item[OVSEC_KADM_BAD_AUX_ATTR] Invalid auxillary attributes.
435 \item[OVSEC_KADM_BAD_HISTORY] Invalid password history count.
436 \item[OVSEC_KADM_BAD_MIN_PASS_LIFE] Password minimum life is greater
437 then password maximum life.
438 \item[OVSEC_KADM_PASS_Q_TOOSHORT] Password is too short.
439 \item[OVSEC_KADM_PASS_Q_CLASS] Password does not contain enough
441 \item[OVSEC_KADM_PASS_Q_DICT] Password is in the password dictionary.
442 \item[OVSEC_KADM_PASS_REUSE] Cannot resuse password.
443 \item[OVSEC_KADM_PASS_TOOSOON] Current password's minimum life has not
445 \item[OVSEC_KADM_POLICY_REF] Policy reference count is not zero.
446 \item[OVSEC_KADM_INIT] Connection to server already initialized.
447 \item[OVSEC_KADM_BAD_PASSWORD] Incorrect password.
450 \subsection{Authentication and Authorization}
453 Two Kerberos principals exist for use in communicating with the Admin
454 system: ovsec_kadm/admin and ovsec_kadm/changepw. Both principals
455 have the KRB5_KDB_DISALLOW_TGT_BASED bit set in their attributes so
456 that service tickets for them can only be acquired via a
457 password-based (AS_REQ) request. Additionally, ovsec_kadm/changepw
458 has the KRB5_KDB_PWCHANGE_SERVICE bit set so that a principal with an
459 expired password can still obtain a service ticket for it.
461 The Admin system accepts requests that are authenticated to either
462 service principal, but the set of operations that can be performed by
463 a request authenticated to each service are different. In particular,
464 only the functions chpass_principal, randkey_principal, get_principal,
465 and get_policy can be performed by a request authenticated to the
466 ovsec_kadm/changepw service. The function semantics describe the precise
469 Each Admin API operation authenticated to the ovsec_kadm/admin service
470 requires a specific authorization to run. This version uses a simple
471 named privilege system with the following names and meanings:
474 \item[Get] Able to examine the attributes (NOT key data) of principals
476 \item[Add] Able to add principals and policies.
477 \item[Modify] Able to modify attributes of existing principals and policies.
478 \item[Delete] Able to remove principals and policies.
481 Privileges are specified via an external configuration file on the
482 Kerberos master server (see section \ref{sec:acls}).
484 Table \ref{tab:func-overview} summarizes the authorization
485 requirements of each function. Additionally, each API function
486 description identifies the privilege required to perform it.
488 \subsection{Function Overview}
490 The functions provided by the Admin API, and the authorization they
491 require, are listed in the table \ref{tab:func-overview}. The
492 ``ovsec_kadm_'' prefix has been removed from each function name.
494 The function semantics in the following sections omit details that are
495 the same for every function.
498 \item The effects of every function are atomic.
500 \item Every function performs an authorization check and returns
501 the appropriate OVSEC_KADM_AUTH_* error code if the caller does not
502 have the required privilege. No other information or error code is
503 ever returned to an unauthorized user.
505 \item Every function checks its arguments for NULL pointers or other
506 obviously invalid values, and returns EINVAL if any are detected.
508 \item Any function that performs a policy check uses the policy named
509 in the principal's policy field. If the POLICY bit is not set in the
510 principal's aux_attributes field, however, the principal has no
511 policy, so the policy check is not performed.
513 \item Unless otherwise specified, all functions return OVSEC_KADM_OK.
517 \caption{Summary of functions and required authorization.}
518 \label{tab:func-overview}
519 \begin{tabular}{@{}llp{3.24in}}
521 {\bf Function Name} & {\bf Authorization} & {\bf Operation} \\
523 init & none & Open a connection with the ovsec_kadm library. \\
524 destroy & none & Close the connection with the ovsec_kadm library. \\
525 create_principal & add & Create a new principal. \\
526 delete_principal & delete & Delete a principal. \\
527 modify_principal & modify & Modify the attributes of an existing
528 principal (not password). \\
529 rename_principal & add and delete & Rename a principal. \\
530 get_principal & get\footnotemark & Retrieve a principal. \\
531 chpass_principal & modify\footnotemark[\thefootnote] &
532 Change a principal's password. \\
533 chpass_principal_util & modify\footnotemark[\thefootnote] & Utility wrapper around chpass_principal. \\
534 randkey_principal & modify\footnotemark[\thefootnote] &
535 Randomize a principal's key. \\
536 create_policy & add & Create a new policy. \\
537 delete_policy & delete & Delete a policy. \\
538 modify_policy & modify & Modify the attributes of a policy. \\
539 get_policy & get & Retrieve a policy. \\
540 free_principal_ent & none & Free the memory associated with an
541 ovsec_kadm_principal_ent_t. \\
542 free_policy_ent & none & Free the memory associated with an
543 ovsec_kadm_policy_ent_t. \\
544 get_privs & none & Return the caller's admin server privileges.
547 \footnotetext[\thefootnote]{These functions also allow a principal to
548 perform the operation on itself; see the function's semantics for
551 \subsection{ovsec_kadm_init}
554 ovsec_kadm_ret_t ovsec_kadm_init(char *client_name, char *pass,
555 char *service_name, char *realm)
558 AUTHORIZATION REQUIRED: none
560 Open a connection to the ovsec_kadm library and initialize any
561 neccessary state information. This function behaves differently when
562 called from local and remote clients.
564 For remote clients, the semantics are:
567 \item Initializes all the com_err error tables used by the Admin
570 \item Acquire a Kerberos ticket for the specified service.
573 \item The ticket's client is client_name, which can be any valid
574 Kerberos principal. If client_name does not include a realm, the
575 default realm of the local host is used
576 \item The ticket's service is service_name@realm. service_name must
577 be one of the constants OVSEC_KADM_ADMIN_SERVICE or
578 OVSEC_KADM_CHANGEPW_SERVICE.
579 \item If realm is NULL, client_name's realm is used.
580 \item The ticket is decoded with the password pass, which must be
581 client_name's password. If pass is NULL, the user is prompted (via
582 the tty) for a password.
585 \item Create a GSS-API authenticated connection to the Admin server,
586 using the just-acquired Kerberos ticket.
589 Local clients, running on the KDC, may be useful. For now this is will
590 most likely be used for testing, but could in the future be the basis
591 for a command-line system that works both remotely and on the KDC
592 machine. If ovsec_kadm_init is invoked locally its semantics are:
595 \item Initializes all the com_err error tables used by the Admin
598 \item Initializes direct access to the KDC database. If pass is NULL,
599 reads the master password from /.k5.REALM-NAME (created by kstash).
600 Otherwise, the non-NULL password is ignored and the user is prompted
603 \item Initializes the dictionary (if present) for dictionary checks.
605 \item Parses client_name as a Kerberos principal and initializes the
606 global current_caller principal to it. client_name should usually be
607 specified as the name of the program.
609 \item The service_name argument is not used.
615 \item[OVSEC_KADM_NO_SRV] No Admin server can be found for the
618 \item[OVSEC_KADM_RPC_ERROR] The RPC connection to the server cannot be
621 \item[OVSEC_KADM_BAD_PASSWORD] Incorrect password.
624 \subsection{ovsec_kadm_destroy}
627 ovsec_kadm_ret_t ovsec_kadm_destroy()
630 AUTHORIZATION REQUIRED: none
632 Close the connection to the Admin server and releases all related
633 resources. This function behaves differently when called by local and
636 For remote clients, the semantics are:
639 \item Destroy the temporary credential cache created by
642 \item Tear down the GSS-API context negotiated with the server.
644 \item Close the RPC connection.
647 For local clients, this function does nothing.
651 \subsection{ovsec_kadm_create_principal}
655 ovsec_kadm_create_principal(ovsec_kadm_principal_ent_t princ, u_int32 mask,
659 AUTHORIZATION REQUIRED: add
663 \item Return OVSEC_KADM_BAD_MASK if the mask is invalid.
664 \item If the named principal exists, return OVSEC_KADM_DUP.
665 \item If the POLICY bit is set and the named policy does not exist,
666 return OVSEC_KADM_UNK_POLICY.
667 \item If OVSEC_KADM_POLICY bit is set in aux_attributes check to see if
668 the password does not meets quality standards, return the appropriate
669 OVSEC_KADM_PASS_Q_* error code if it fails.
670 \item Store the principal, set the key. The key is generated with
671 Kerberos' string-to-key function, using the salt method specified on
672 the admin server's command line; see section \ref{sec:commandline}.
673 \item If the POLICY bit is set, increment the named policy's reference
676 \item Set the pw_expiration field.
678 \item If the POLICY bit is not set, then
680 \item if the PW_EXPIRATION bit is set, set pw_expiration to the given
682 \item set pw_expiration to never.
684 \item Otherwise, if the PW_EXPIRATION bit is set, set pw_expiration to
685 the sooner of the given value and now + pw_max_life.
686 \item Otherwise, set pw_expiration to now + pw_max_life.
689 \item Set mod_date to now and set mod_name to caller.
690 \item Set last_pwd_change to now.
696 \item[OVSEC_KADM_BAD_MASK] The field mask is invalid for a create
698 \item[OVSEC_KADM_DUP] Principal already exists.
699 \item[OVSEC_KADM_UNK_POLICY] Policy named in entry does not exist.
700 \item[OVSEC_KADM_PASS_Q_*] Specified password does not meet policy
704 \subsection{ovsec_kadm_delete_principal}
708 ovsec_kadm_delete_principal(krb5_principal princ);
711 AUTHORIZATION REQUIRED: delete
714 \item Return OVSEC_KADM_UNK_PRINC if the principal does not exist.
715 \item If the POLICY bit is set in aux_attributes, decrement the named
716 policy's reference count by one.
717 \item Delete principal.
723 \item[OVSEC_KADM_UNK_PRINC] Principal does not exist.
726 \subsection{ovsec_kadm_modify_principal}
730 ovsec_kadm_modify_principal(ovsec_kadm_principal_ent_t princ, u_int32 mask);
733 Modify the attributes of the principal named in
734 ovsec_kadm_principal_ent_t. This does not allow the principal to be
735 renamed or for its password to be changed.
737 AUTHORIZATION REQUIRED: modify
739 Although a principal's pw_expiration is usually computed based on its
740 policy and the time at which it changes its password, this function
741 also allows it to be specified explicitly. This allows an
742 administrator, for example, to create a principal and assign it to a
743 policy with a pw_max_life of one month, but to declare that the new
744 principal must change its password away from its initial value
745 sometime within the first week.
748 \item Return OVSEC_KADM_UNK_PRINC if the principal does not exist.
749 \item Return OVSEC_KADM_BAD_MASK if the mask is invalid.
750 \item If POLICY bit is set but the new policy does not exist, return
751 OVSEC_KADM_UNK_POLICY.
752 \item If either the POLICY or POLICY_CLR bits are set, update the
753 corresponding bits in aux_attributes.
755 \item Update policy reference counts.
757 \item If the POLICY bit is set, then increment policy count on new
759 \item If the POLICY or POLICY_CLR bit is set, and the POLICY bit in
760 aux_attributes is set, decrement policy count on old policy.
763 \item Set pw_expiration according to the new policy.
765 \item If the POLICY bit is not set in aux_attributes, then
767 \item if the PW_EXPIRATION bit is set, set pw_expiration to the given
769 \item set pw_expiration to never.
771 \item Otherwise, if the PW_EXPIRATION bit is set, set pw_expiration to
772 the sooner of the given value and last_pwd_change + pw_max_life.
773 \item Otherwise, set pw_expiration to last_pwd_change + pw_max_life.
776 \item Update the fields specified in the mask.
777 \item Update mod_name field to caller and mod_date to now.
783 \item[OVSEC_KADM_UNK_PRINC] Entry does not exist.
784 \item[OVSEC_KADM_BAD_MASK] The mask is not valid for a modify
786 \item[OVSEC_KADM_UNK_POLICY] The POLICY bit is set but the new
787 policy does not exist.
790 \subsection{ovsec_kadm_rename_principal}
794 ovsec_kadm_rename_principal(krb5_principal source, krb5_principal target);
797 AUTHORIZATION REQUIRED: add and delete
800 \item Check to see if source principal exists, if not return
801 OVSEC_KADM_UNK_PRINC error.
802 \item Check to see if target exists, if so return OVSEC_KADM_DUP error.
803 \item Create the new principal named target, then delete the old
804 principal named source. All of target's fields will be the same as
805 source's fields, except that mod_name and mod_date will be updated to
806 reflect the current caller and time.
809 Note that since the principal name may have been used as the salt for
810 the principal's key, renaming the principal may render the principal's
811 current password useless; with the new salt, the key generated by
812 string-to-key on the password will suddenly be different. Therefore,
813 an application that renames a principal must also require the user to
814 specify a new password for the principal (and administrators should
815 notify the affected party).
817 Note also that, by the same argument, renaming a principal will
818 invalidate that principal's password history information; since the
819 salt will be different, a user will be able to select a previous
820 password without error.
825 \item[OVSEC_KADM_UNK_PRINC] Source principal does not exist.
826 \item[OVSEC_KADM_DUP] Target principal already exist.
829 \subsection{ovsec_kadm_chpass_principal}
833 ovsec_kadm_chpass_principal(krb5_principal princ, char *pw);
836 AUTHORIZATION REQUIRED: modify, or the calling principal being the
837 same as the princ argument. If the request is authenticated to the
838 ovsec_kadm/changepw service, the modify privilege is disregarded.
840 Change a principal's password.
842 This function enforces password policy and dictionary checks. If the
843 new password specified is in the password dictionary,
844 OVSEC_KADM_PASS_DICT is returned (even if the policy bit is not set).
845 If the principal's POLICY bit is set in aux_attributes, compliance
846 with each of the named policy fields is verified and an appropriate
847 error code is returned if verification fails.
849 Note that the policy checks are only be performed if the POLICY bit is
850 set in the principal's aux_attributes field.
853 \item Make sure principal exists, if not return OVSEC_KADM_UNK_PRINC error.
854 \item If caller does not have modify privilege, (now - last_pwd_change) $<$
855 pw_min_life, and the KRB5_KDB_REQUIRES_PWCHANGE bit is not set in the
856 principal's attributes, return OVSEC_KADM_PASS_TOOSOON.
857 \item If the password does not meet the quality
858 standards, return the appropriate OVSEC_KADM_PASS_Q_* error code.
859 \item Convert password to key. The key is generated with
860 Kerberos' string-to-key function, using the salt method specified on
861 the admin server's command line; see section \ref{sec:commandline}.
862 \item If the new key is in the principal's password history, return
863 OVSEC_KADM_PASS_REUSE.
864 \item Store old key in history.
865 \item Update principal to have new key.
866 \item Increment principal's key version number by one.
867 \item If the POLICY bit is set, set pw_expiration to now +
868 max_pw_life. If the POLICY bit is not set, set pw_expiration to
870 \item If the KRB5_KDB_REQUIRES_PWCHANGE bit is set in the principal's
871 attributes, clear it.
872 \item Update last_pwd_change and mod_date to now, update mod_name to
879 \item[OVSEC_KADM_UNK_PRINC] Principal does not exist.
880 \item[OVSEC_KADM_PASS_Q_*] Requested password does not meet quality
882 \item[OVSEC_KADM_PASS_REUSE] Requested password is in user's
884 \item[OVSEC_KADM_PASS_TOOSOON] Current password has not reached minimum
889 \subsection{ovsec_kadm_chpass_principal_util}
893 ovsec_kadm_chpass_principal_util(krb5_principal princ, char *new_pw,
894 char **pw_ret, char *msg_ret);
897 AUTHORIZATION REQUIRED: modify, or the calling principal being the
898 same as the princ argument. If the request is authenticated to the
899 ovsec_kadm/changepw service, the modify privilege is disregarded.
901 This function is a wrapper around ovsec_kadm_chpass_principal. It can
902 read a new password from a user, change a principal's password, and
903 return detailed error messages. msg_ret should point to a char buffer
904 in the caller's space of sufficient length for the error messages
905 described below. 1024 bytes is recommended. It will also return the
906 new password to the caller if pw_ret is non-NULL.
909 \item If new_pw is NULL, this routine will prompt the user for the new
910 password (using the strings specified by OVSEC_KADM_PW_FIRST_PROMPT and
911 OVSEC_KADM_PW_SECOND_PROMPT) and read (without echoing) the password input.
912 Since it is likely that this will simply call krb5_read_password only
913 terminal-based applications will make use of the password reading
914 functionality. If the passwords don't match the string ``New passwords do
915 not match - password not changed.'' will be copied into msg_ret, and the
916 error code KRB5_LIBOS_BADPWDMATCH will be returned. For other errors that
917 ocurr while reading the new password, copy the string ``<com_err message$>$
918 occurred while trying to read new password.'' followed by a blank line and
919 the string specified by CHPASS_UTIL_PASSWORD_NOT_CHANGED into msg_ret and
920 return the error code returned by krb5_read_password.
922 \item If pw_ret is non-NULL, and the password was prompted, set *pw_ret to
923 point to a static buffer containing the password. If pw_ret is non-NULL
924 and the password was supplied, set *pw_ret to the supplied password.
926 \item Call ovsec_kadm_chpass_principal with princ, and new_pw.
928 \item If successful copy the string specified by CHPASS_UTIL_PASSWORD_CHANGED
929 into msg_ret and return zero.
931 \item For a policy related failure copy the appropriate message (from below)
932 followed by a newline and ``Password not changed.'' into msg_ret
933 filling in the parameters from the principal's policy information. If
934 the policy information cannot be obtained copy the generic message if
935 one is specified below. Return the error code from
936 ovsec_kadm_chpass_principal.
941 \item[PASS_Q_TOO_SHORT]
942 New password is too short. Please choose a
943 password which is more than $<$pw-min-len$>$ characters.
945 \item[PASS_Q_TOO_SHORT - generic]
946 New password is too short. Please choose a longer password.
949 New password was used previously. Please choose a
953 New password does not have enough character classes. Classes include
954 lower class letters, upper case letters, digits, punctuation and all
955 other characters. Please choose a password with at least
956 $<$min-classes$>$ character classes.
958 \item[PASS_Q_CLASS - generic]
959 New password does not have enough character classes. Classes include
960 lower class letters, upper case letters, digits, punctuation and all
964 New password was found in a dictionary of possible passwords and
965 therefore may be easily guessed. Please choose another password. See
966 the kpasswd man page for help in choosing a good password.
969 Password cannot be changed because it was changed too recently. Please
970 wait until $<$last-pw-change+pw-min-life$>$ before you change it. If you
971 need to change your password before then, contact your system
972 security administrator.
974 \item[PASS_TOOSOON - generic]
975 Password cannot be changed because it was changed too recently. If you
976 need to change your now please contact your system security
980 \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.
987 \item[KRB5_LIBOS_BADPWDMATCH] Typed new passwords did not match.
988 \item[OVSEC_KADM_UNK_PRINC] Principal does not exist.
989 \item[OVSEC_KADM_PASS_Q_*] Requested password does not meet quality
991 \item[OVSEC_KADM_PASS_REUSE] Requested password is in user's
993 \item[OVSEC_KADM_PASS_TOOSOON] Current password has not reached minimum
998 \subsection{ovsec_kadm_randkey_principal}
1002 ovsec_kadm_randkey_principal(krb5_principal princ, krb5_keyblock **new_key)
1005 AUTHORIZATION REQUIRED: modify, or the calling principal being the
1006 same as the princ argument. If the request is authenticated to the
1007 ovsec_kadm/changepw service, the modify privilege is disregarded.
1009 Generate and assign a new random key to the named principal, and
1010 return the generated key in allocated storage. The caller must free
1011 the returned krb5_keyblock * with krb5_free_keyblock.
1013 If the principal's POLICY bit is set in aux_attributes and the caller does
1014 not have modify privilege , compliance with the password minimum life
1015 specified by the policy is verified and an appropriate error code is returned
1016 if verification fails.
1019 \item If the principal does not exist, return OVSEC_KADM_UNK_PRINC.
1020 \item If caller does not have modify privilege, (now - last_pwd_change) $<$
1021 pw_min_life, and the KRB5_KDB_REQUIRES_PWCHANGE bit is not set in the
1022 principal's attributes, return OVSEC_KADM_PASS_TOOSOON.
1023 \item Store old key in history.
1024 \item Update principal to have new key.
1025 \item Increment principal's key version number by one.
1026 \item If the POLICY bit in aux_attributes is set, set pw_expiration to
1028 \item If the KRB5_KDC_REQUIRES_PWCHANGE bit is set in the principal's
1029 attributes, clear it.
1030 \item Update last_pwd_change and mod_date to now, update mod_name to
1037 \item[OVSEC_KADM_UNK_PRINC] Principal does not exist.
1038 \item[OVSEC_KADM_PASS_TOOSOON] The minimum lifetime for the current
1039 key has not expired.
1042 This function can also be used as part of a sequence to create a new
1043 principal with a random key. The steps to perform the operation
1047 \item Create the principal with ovsec_kadm_create_principal with a
1048 random password string and with the KRB5_KDB_DISALLOW_ALL_TIX bit set
1049 in the attributes field.
1051 \item Randomize the principal's key with ovsec_kadm_randkey_principal.
1053 \item Call ovsec_kadm_modify_principal to reset the
1054 KRB5_KDB_DISALLOW_ALL_TIX bit in the attributes field.
1057 The three steps are necessary to ensure secure creation. Since an
1058 attacker might be able to guess the initial password assigned by the
1059 client program, the principal must be disabled until the key can be
1062 \subsection{ovsec_kadm_get_principal}
1066 ovsec_kadm_get_principal(krb5_principal princ,
1067 ovsec_kadm_principal_ent_t *ent);
1070 Return the principal's attributes in allocated memory. The caller
1071 must free the returned entry with ovsec_kadm_free_principal_ent.
1073 AUTHORIZATION REQUIRED: get, or the calling principal being the same
1074 as the princ argument. If the request is authenticated to the
1075 ovsec_kadm/changepw service, the get privilege is disregarded.
1081 \item[OVSEC_KADM_UNK_PRINC] Principal does not exist.
1084 \subsection{ovsec_kadm_create_policy}
1088 ovsec_kadm_create_policy(ovsec_kadm_policy_ent_t policy, u_int32 mask);
1091 Create a new policy.
1093 AUTHORIZATION REQUIRED: add
1096 \item Check to see if mask is valid, if not return OVSEC_KADM_BAD_MASK error.
1097 \item Return OVSEC_KADM_BAD_POLICY if the policy name contains illegal
1100 \item Check to see if the policy already exists, if so return
1101 OVSEC_KADM_DUP error.
1102 \item If the PW_MIN_CLASSES bit is set and pw_min_classes is not 1, 2,
1103 3, 4, or 5, return OVSEC_KADM_BAD_CLASS.
1104 \item Create a new policy setting the appropriate fields determined
1111 \item[OVSEC_KADM_DUP] Policy already exists
1112 \item[OVSEC_KADM_BAD_MASK] The mask is not valid for a create
1114 \item[OVSEC_KADM_BAD_CLASS] The specified number of character classes
1116 \item[OVSEC_KADM_BAD_POLICY] The policy name contains illegal characters.
1119 \subsection{ovsec_kadm_delete_policy}
1123 ovsec_kadm_delete_policy(char *policy);
1128 AUTHORIZATION REQUIRED: delete
1131 \item Return OVSEC_KADM_BAD_POLICY if the policy name contains illegal
1133 \item Return OVSEC_KADM_UNK_POLICY if the named policy does not exist.
1134 \item Return OVSEC_KADM_POLICY_REF if the named policy's refcnt is not 0.
1135 \item Delete policy.
1141 \item[OVSEC_KADM_BAD_POLICY] The policy name contains illegal characters.
1142 \item[OVSEC_KADM_UNK_POLICY] Policy does not exist.
1143 \item[OVSEC_KADM_POLICY_REF] Policy is being referenced.
1146 \subsection{ovsec_kadm_modify_policy}
1150 ovsec_kadm_modify_policy(ovsec_kadm_policy_ent_t policy, u_int32 mask);
1153 Modify an existing policy. Note that modifying a policy has no affect
1154 on a principal using the policy until the next time the principal's
1155 password is changed.
1157 AUTHORIZATION REQUIRED: modify
1160 \item Return OVSEC_KADM_BAD_POLICY if the policy name contains illegal
1162 \item Check to see if mask is legal, if not return OVSEC_KADM_BAD_MASK error.
1163 \item Check to see if policy exists, if not return
1164 OVSEC_KADM_UNK_POLICY error.
1165 \item If the PW_MIN_CLASSES bit is set and pw_min_classes is not 1, 2,
1166 3, 4, or 5, return OVSEC_KADM_BAD_CLASS.
1167 \item Update the fields specified in the mask.
1173 \item[OVSEC_KADM_BAD_POLICY] The policy name contains illegal characters.
1174 \item[OVSEC_KADM_UNK_POLICY] Policy not found.
1175 \item[OVSEC_KADM_BAD_MASK] The mask is not valid for a modify
1177 \item[OVSEC_KADM_BAD_CLASS] The specified number of character classes
1181 \subsection{ovsec_kadm_get_policy}
1185 ovsec_kadm_get_policy(char *policy, ovsec_kadm_policy_ent_t *ent);
1188 AUTHORIZATION REQUIRED: get, or the calling principal's policy being
1189 the same as the policy argument. If the request is authenticated to
1190 the ovsec_kadm/changepw service, the get privilege is disregarded.
1192 Return the policy's attributes in allocated memory. The caller must
1193 free the returned entry with ovsec_kadm_free_policy_ent.
1198 \item[OVSEC_KADM_BAD_POLICY] The policy name contains illegal characters.
1199 \item[OVSEC_KADM_UNK_POLICY] Policy not found.
1202 \subsection{ovsec_kadm_free_principal_ent, _policy_ent}
1205 void ovsec_kadm_free_principal_ent(ovsec_kadm_principal_ent_t princ);
1208 Free the memory that was allocated by a call to
1209 ovsec_kadm_get_principal. If the argument is NULL, the function
1210 returns succesfully.
1212 AUTHORIZATION REQUIRED: none (local operation)
1215 void ovsec_kadm_free_policy_ent(ovsec_kadm_policy_ent_t policy);
1218 Free memory that was allocated by a call to ovsec_kadm_get_policy. If
1219 the argument is NULL, the function returns succesfully.
1221 AUTHORIZATION REQUIRED: none (local operation)
1223 \subsection{ovsec_kadm_get_privs}
1227 ovsec_kadm_get_privs(u_int32 *privs);
1230 Return the caller's admin server privileges in the integer pointed to
1231 by the argument. The Admin API does not define any way for a
1232 principal's privileges to be set. Note that this function will
1233 probably be removed or drastically changed in future versions of this
1236 The returned value is a bitmask indicating the caller's privileges:
1238 \begin{tabular}{llr}
1239 {\bf Privilege} & {\bf Symbol} & {\bf Value} \\
1240 Get & OVSEC_KADM_PRIV_GET & 0x01 \\
1241 Add & OVSEC_KADM_PRIV_ADD & 0x02 \\
1242 Modify & OVSEC_KADM_PRIV_MODIFY & 0x04 \\
1243 Delete & OVSEC_KADM_PRIV_DELETE & 0x08
1246 There is no guarantee that a caller will have a privilege indicated by
1247 this function for any length of time; applications using this function
1248 must still be prepared to handle all possible OVSEC_KADM_AUTH_* error
1253 The Admin API will be implemented by a server process running on the
1254 same machine as the Kerberos server, and a client library to
1255 communicate with the server.
1257 \subsection{Command Line}
1258 \label{sec:commandline}
1260 The command line syntax of the admin server is
1263 ovsec_adm_server [-m] [-r realm] [-createsalt normal|none]
1264 [-modifysalt normal|none|keep]
1267 The -m argument specifies that the Kerberos master key should be read
1268 from the keyboard instead of from the stash file. If the stash file
1269 does not exist and this argument is not specified, the server will
1272 The -r argument specifies the Kerberos realm. If this argument is not
1273 specified, the host's default realm is used.
1275 The -createsalt and -modifysalt arguments control the type of salt
1276 used when creating and modifying keys in the Kerberos database,
1277 respectively. ``normal'' means the standard V5 salt which uses the
1278 principal and realm name. ``none'' means no salt, which is compatible
1279 with Kerberos V4. ``keep'' means maintain the previous salt when a
1282 If the either admin principal or policy databases are reloaded using
1283 the tools described in section \ref{sec:tools}, the admin server must
1284 be shut down during the process. If the admin server is left running
1285 during the import process, at best the server may use old information
1286 and at worst the database may become inconsistent.
1288 \subsection{Protocol and Port Number}
1290 The admin server accepts TCP Sun RPC connections. The port number
1291 (which the server listens on, and which clients should use to contact
1292 it) is determined by a three step process:
1295 \item If ovsec_kadm/tcp exists in /etc/services, the specified port
1298 \item Otherwise, if kerberos_adm/tcp exists in /etc/services, the
1299 specified port number is used.
1301 \item Otherwise, port number 752 is used.
1304 \subsection{Key Table, Authorization ACLs}
1307 The admin server's keytable is stored in /krb5/ovsec_admin.srvtab. It
1308 contains entries for the principals ovsec_kadm/admin and
1309 ovsec_kadm/changepw.
1311 The admin server will use a simple ACL mechanism to grant privileges
1312 to principals. The file {\tt /krb5/ovsec_admin_acl} will contain a
1313 list of principals and their privileges. It is read at start-up, and
1314 can only be reread by restarting the admin server.
1316 The format of this file is:
1319 \item Blank lines or lines beginning with ``\#'' are ignored.
1321 \item ACL entry lines contain two fields separated by any number of
1322 spaces, tabs, or newlines, and are terminated with a semi-colon. The
1323 first field is a Kerberos name and the second field is the privilege
1326 \item The privilege list can contain a comma separated list of the
1327 words ``get'', ``add'', ``modify'', and ``delete''.
1330 The principal named in the first field of each ACL entry has the
1331 privileges listed in the second field the ACL entry.
1333 \subsection{Logging}
1335 The Admin server will log various events via the syslog mechanism (see
1336 the syslog(3) manual page). The level depends on the notice, the
1337 facility is LOG_LOCAL6, and notices are identified with the name
1338 ``ovsec_adm_server''. Each syslog message described below begins with
1339 a prefix including the time the message was logged, the host name of
1340 the logging machine, and the pid of the logging process:
1343 Nov 11 12:37:26 suan-la-chow-show ovsec_adm_server[9229]: <message>
1346 \subsubsection{Miscellaneous Messages}
1348 When the server starts successfully and is ready to handle requests,
1349 is logs the message ``starting'' at the LOG_INFO level. When it exits
1350 (due to a signal, for example) it logs the message ``finished,
1351 exiting'' at the LOG_INFO level.
1353 If the dictionary file does not exist, the server logs the message
1354 ``WARNING: Cannot find the dictionary file $<$name$>$, continuing
1355 without one.'' at the LOG_ERR level and continues with dictionary
1358 If the server cannot register itself as an RPC server via the portmap
1359 daemon, it logs the message ``Cannot register RPC service, failing.''
1360 at the LOG_ERR level and exits with non-zero status. This error can
1361 happen if the portmapper is not running.
1363 If the GSS-API authentication system cannot be initialized, the server
1364 logs the message ``Cannot initialize GSS-API authentication,
1365 failing.'' at the LOG_ERR level and exits with non-zero status. This
1366 error can happen if, for example, the file ovsec_adm.srvtab does not
1367 exist or is incorrect.
1369 \subsubsection{Request Messages}
1371 In the event descriptions below, IP address refers to the originating
1372 remote IP address, procedure name refers to the name of the API
1373 function, client name refers to the authenticated name of the caller,
1374 service name refers to the service the client authenticated to (see
1375 section \ref{sec:auth}), primary argument refers to the name of the
1376 principal or policy affected by the call,\footnote{The first release
1377 only logs the primary argument, rather than logging the old and new
1378 values of all fields.} and status refers to the com_err string
1379 corresponding to the error code generated. All of these messages are
1380 logged at the LOG_NOTICE level.
1383 \item Unsuccessful authentication attempts (e.g.: failures during
1384 GSS-API context establishment). This error occurs inside the RPC; the
1385 admin server is notified via a callback.
1388 Authentication attempt failed: <IP address>, <GSS-API error strings>
1391 Example: A buggy client attempts to authenticate to the admin server
1392 as the existing but invalid service name ``mailserver@REALM.COM'':
1395 Authentication attempt failed: 192.231.148.11, Miscellaneous error, Wrong
1396 principal in request
1399 \item Authentication failure. This error can occur both within the
1400 RPC, while parsing the RPC call header, and while arguments are
1401 decoded by the admin server. It can be the result of a a garbled
1402 {\it or retransmitted} packet, a replay attack, a packet-modification
1403 attack, or a header/argument splicing attack.
1406 WARNING! Forged/garbled request: <procedure name>, claimed client = <client
1407 name>, service = <service name>, addr = <IP address>
1410 Example: An attacker attempts to replay a previously valid ``create
1411 principal'' message from jon/admin@REALM.COM:
1414 WARNING! Forged/garbled request: ovsec_kadm_create_principal, claimed client =
1415 jon/admin@REALM.COM, service = admin@REALM.COM, addr = 192.231.148.12
1418 \item Unauthorized request. This error occurs when a properly
1419 authenticated caller attempts to perform an operation for which it is
1423 Unauthorized request: <procedure name>, <primary argument>, client =
1424 <client name>, service = <service name>, addr = <IP address>
1427 Example: An attacker cracker@REALM.COM attempts to modify the Kerberos
1431 Unauthorized request: ovsec_kadm_modify_principal, K/M@REALM.COM,
1432 client = cracker@REALM.COM, service = admin@REALM.COM, addr =
1436 \item Authorized requests and miscellaneous errors. A message is
1437 logged when an authorized request succeeds or fails for any reason
1438 other than those listed above. In the case of success, the status is
1439 ``success''; otherwise, the status can be anything from ``no space
1440 left on device'' (ENOSPC) to an OVSEC_KADM error such as ``principal
1441 does not exist'' (OVSEC_KADM_UNK_PRINC).
1444 Request: <procedure name>, <primary argument>, <status>, client =
1445 <client name>, service = <service name>, addr = <IP address>
1448 Example: jon/admin@REALM.COM creates a new principal new@REALM.COM:
1451 Request: ovsec_kadm_create_principal, new@REALM.COM, success,
1452 client = jon/admin@REALM.COM, service = admin@REALM.COM, addr =
1456 Example: A buggy client program attempts to create a principal with a
1460 Request: ovsec_kadm_create_principal, (null), Invalid argument, client
1461 = jon/admin@REALM.COM, service = admin@REALM.COM, addr =
1465 Example: joe/user@REALM.COM changes its own password:
1468 Request: ovsec_kadm_chpass_principal, joe/user@REALM.COM, success,
1469 client = joe/user@REALM.COM, server = ovsec_kadm/changepw@REALM.COM,
1470 addr = 192.231.148.12
1473 Example: jon/admin@REALM.COM attempts to get a principal that does not
1477 Request: ovsec_kadm_get_principal, does/not/exist@REALM.COM, principal
1478 does not exist, client = jon/admin@REALM.COM, server =
1479 admin@REALM.COM, addr = 192.231.148.12
1484 \subsection{Password Dictionary}
1486 The Admin server's password dictionary is stored in
1487 /krb5/ovsec_adm_dict. It is read once when the server starts. It
1488 contains a list of entries, separated by newlines. An entry may
1489 include any character except a newline and NULL, including spaces.
1490 The dictionary does not need to be sorted.
1495 Three tools will be provided to create and manage the admin databases.
1496 This need only run on the admin server machine and do not need to
1497 operate remotely. The tools are:
1500 \item[ovsec_adm_create] create the admin service principal, the admin
1501 history principal, the admin password-changing principal, and empty
1502 admin policy database, and an admin principal database with an empty
1503 entry for every exist principal.
1504 \item[ovsec_adm_db_export/import] dump or load the admin policy and
1506 \item[ovsec_adm_check] check the KDC and admin databases for
1507 inconsistencies and repair them.
1510 The details of these tools are described in their own documents.