Next: kadm5_flush
Up: Functions
Previous: Overview
Contents
In KADM5_API_VERSION 1:
kadm5_ret_t kadm5_init_with_password(char *client_name, char *pass,
char *service_name, char *realm,
unsigned long struct_version,
unsigned long api_version,
void **server_handle)
kadm5_ret_t kadm5_init_with_skey(char *client_name, char *keytab,
char *service_name, char *realm,
unsigned long struct_version,
unsigned long api_version,
void **server_handle)
kadm5_ret_t kadm5_init(char *client_name, char *pass,
char *service_name, char *realm,
unsigned long struct_version,
unsigned long api_version,
void **server_handle)
In KADM5_API_VERSION 2:
kadm5_ret_t kadm5_init_with_password(char *client_name, char *pass,
char *service_name,
kadm5_config_params *realm_params,
unsigned long struct_version,
unsigned long api_version,
void **server_handle)
kadm5_ret_t kadm5_init_with_skey(char *client_name, char *keytab,
char *service_name,
kadm5_config_params *realm_params,
unsigned long struct_version,
unsigned long api_version,
void **server_handle)
kadm5_ret_t kadm5_init(char *client_name, char *pass,
char *service_name,
kadm5_config_params *realm_params,
unsigned long struct_version,
unsigned long api_version,
void **server_handle)
kadm5_ret_t kadm5_init_with_creds(char *client_name,
krb5_ccache ccache,
char *service_name,
kadm5_config_params *params,
krb5_ui_4 struct_version,
krb5_ui_4 api_version,
void **server_handle)
AUTHORIZATION REQUIRED: none
NOTE: kadm5_init is an obsolete function provided for backwards
compatibility. It is identical to kadm5_init_with_password.
These three functions open a connection to the kadm5 library and
initialize any neccessary state information. They behave differently
when called from local and remote clients.
In KADM5_API_VERSION_2, these functions take a kadm5_config_params
structure instead of a realm name as an argument. The semantics are
similar: if a NULL pointer is passed for the realm_params argument,
the default realm and default parameters for that realm, as specified
in the krb5 configuration file (e.g. /etc/krb5.conf) are used. If a
realm_params structure is provided, the fields that are set override
the default values. If a parameter is specified to the local or
remote libraries that does not apply to that side, an error code
(KADM5_BAD_CLIENT_PARAMS or KADM5_BAD_SERVER_PARAMS) is returned. See
section 4.3 for a discussion of configuration
parameters.
For remote clients, the semantics are:
- Initializes all the com_err error tables used by the Admin
system.
- Acquires configuration parameters. In KADM5_API_VERSION_1, all
the defaults specified in the configuration file are used, according
to the realm. In KADM5_API_VERSION_2, the values in params_in are
merged with the default values. If an illegal mask value is
specified, KADM5_BAD_CLIENT_PARAMS is returned.
- Acquires a Kerberos ticket for the specified service.
- The ticket's client is client_name, which can be any valid
Kerberos principal. If client_name does not include a realm, the
default realm of the local host is used
- The ticket's service is service_name@realm. service_name must
be one of the constants KADM5_ADMIN_SERVICE or
KADM5_CHANGEPW_SERVICE.
- If realm is NULL, client_name's realm is used.
- For init_with_password, an initial ticket is acquired and
decoded with the password pass, which must be client_name's password.
If pass is NULL or an empty string, the user is prompted (via the tty)
for a password.
- For init_with_skey, an initial ticket is acquired and decoded
with client_name's key obtained from the specified keytab. If keytab
is NULL or an empty string the default keytab is used.
- For init_with_creds, ccache must be an open credential cache
that already has a ticket for the specified client and server.
Alternatively, if a site chooses to disable the DISALLOW_TGT_BASED
flag on the admin and changepw principals, the ccache can contain a
ticket-granting ticket for client_name.
- Creates a GSS-API authenticated connection to the Admin server,
using the just-acquired Kerberos ticket.
- Verifies that the struct_version and api_version specified by
the caller are valid and known to the library.
- Sends the specified api_version to the server.
- Upon successful completion, fills in server_handle with a handle
for this connection, to be used in all subsequent API calls.
The caller should always specify KADM5_STRUCT_VERSION for the
struct_version argument, a valid and supported API version constant
for the api_version argument (currently, KADM5_API_VERSION_1 or
KADM5_API_VERSION_2), and a valid pointer in which the server handle
will be stored.
If any kadm5_init_* is invoked locally its semantics are:
- Initializes all the com_err error tables used by the Admin
system.
- Acquires configuration parameters. In KADM5_API_VERSION_1, all
the defaults specified in the configuration file are used, according
to the realm. In KADM5_API_VERSION_2, the values in params_in are
merged with the default values. If an illegal mask value is
specified, KADM5_BAD_SERVER_PARAMS is returned.
- Initializes direct access to the KDC database. In
KADM5_API_VERISON_1, if pass (or keytab) is NULL or an empty string,
reads the master password from the stash file; otherwise, the non-NULL
password is ignored and the user is prompted for it via the tty. In
KADM5_API_VERSION_2, if the MKEY_FROM_KEYBOARD parameter mask is set
and the value is non-zero, reads the master password from the user via
the tty; otherwise, the master key is read from the stash file.
Calling init_with_skey or init_with_creds with the MKEY_FROM_KEYBOARD
mask set with a non-zero field is illegal, and calling them without
the mask set is exactly like calling init_with_password.
- Initializes the dictionary (if present) for dictionary checks.
- Parses client_name as a Kerberos principal. client_name should
usually be specified as the name of the program.
- Verifies that the struct_version and api_version specified by
the caller are valid.
- Fills in server_handle with a handle containing all state
information (version numbers and client name) for this ``connection.''
The service_name argument is not used.
RETURN CODES:
- KADM5_NO_SRV
- No Admin server can be found for the
specified realm.
- KADM5_RPC_ERROR
- The RPC connection to the server cannot be
initiated.
- KADM5_BAD_PASSWORD
- Incorrect password.
- KADM5_SECURE_PRINC_MISSING
- The principal
KADM5_ADMIN_SERVICE or KADM5_CHANGEPW_SERVICE does not
exist. This is a special-case replacement return code for ``Server
not found in database'' for these required principals.
- KADM5_BAD_CLIENT_PARAMS
- A field in the parameters mask was
specified to the remote client library that is not legal for remote
clients.
- KADM5_BAD_SERVER_PARAMS
- A field in the parameters mask was
specified to the local client library that is not legal for local
clients.
Next: kadm5_flush
Up: Functions
Previous: Overview
Contents
Autobuild
2006-06-16