kadm5_init_*

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:

1. Initializes all the com_err error tables used by the Admin system.

2. 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.

3. Acquires a Kerberos ticket for the specified service.
   1. 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
   2. The ticket's service is service_name@realm. service_name must be one of the constants KADM5_ADMIN_SERVICE or KADM5_CHANGEPW_SERVICE.
   3. If realm is NULL, client_name's realm is used.

   4. 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.

   5. 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.

   6. 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.

4. Creates a GSS-API authenticated connection to the Admin server, using the just-acquired Kerberos ticket.

5. Verifies that the struct_version and api_version specified by the caller are valid and known to the library.

6. Sends the specified api_version to the server.

7. 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:

1. Initializes all the com_err error tables used by the Admin system.

2. 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.

3. 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.

4. Initializes the dictionary (if present) for dictionary checks.

5. Parses client_name as a Kerberos principal. client_name should usually be specified as the name of the program.

6. Verifies that the struct_version and api_version specified by the caller are valid.

7. 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.