sec_key_mgmt_change_key(3sec)
Changes a principal's key
Synopsis
#include <dce/keymgmt.h>
void sec_key_mgmt_change_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
unsigned32 key_vno,
void
*keydata,
sec_timeval_period_t *garbage_collect_time,
error_status_t *status);
Parameters
Input
authn_service
Identifies the authentication protocol using this key. The possible authentication protocols are as follows:
| rpc_c_authn_dce_secret | DCE shared-secret key authentication. |
| rpc_c_authn_dce_public | DCE public key authentication (reserved for future use). |
This parameter can specify either the local key file or an argument to the get_key_fn key acquisition routine of the rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file (/krb/v5srvtab) should be used. A key file name specifies that file should be used as the key file. You must prepend the file's absolute file name with FILE: and the file must have been created with the rgy_edit ktadd command or the sec_key_mgmt_set_key function.
Any other value specifies an argument for the get_key_fn key acquisition routine. See the rpc_server_register_auth_info( ) reference page for more information.
principal_name
A pointer to a character string indicating the name of the principal whose key is to be changed.
key_vno
The version number of the new key. If 0 (zero) is specified, the routine will select the next appropriate key version number.
keydata
A pointer to a structure of type sec_passwd_rec_t.
Output
garbage_collect_time
The number of seconds that must elapse before all currently valid tickets (which are encoded with the current or previous keys) expire. At that time, all
obsolete keys may be garbage collected, since no valid tickets encoded with those keys will remain outstanding on the network.
status
A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error.
Description
The sec_key_mgmt_change_key( ) routine performs all activities necessary to update a principal's key to the specified value. This includes updating any
local storage for the principal's key and also performing any remote operations needed to keep the authentication protocol (or network registry) current. Old keys for the principal are garbage
collected if appropriate.
Files
/usr/include/dce/keymgmt.idl
The idl file from which dce/keymgmt.h was derived.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
Any error condition will leave the key state unchanged.
sec_key_mgmt_e_key_unavailable
The old key is not present and therefore cannot be used to set a client side authentication context.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_auth_unavailable
The authentication protocol is not available to update the network database or to obtain the necessary network credentials.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_key_mgmt_e_key_unsupported
The key type is not supported.
sec_key_mgmt_e_key_version_ex
A key with this version number already exists.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
sec_rgy_object_not_found
No principal was found with the given name.
sec_login_s_no_memory
A memory allocation error occurred.
error_status_ok
The call was successful.
Related Information
Functions:
sec_key_mgmt_gen_rand_key(3sec)