sec_key_mgmt_set_key(3sec)
Inserts a key value into the local storage
Synopsis
#include <dce/keymgmt.h>
void sec_key_mgmt_set_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
unsigned32 key_vno,
void
*keydata,
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.
The file name must begin with FILE:. If the file name does not begin with FILE:, the code will add it.
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 associated with the key to be set.
key_vno
The version number of the key to be set.
keydata
A pointer to the key value to be set.
Output
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_set_key( ) routine performs all local activities necessary to update a principal's key to the specified value. This routine will not
update the authentication protocol's value for the principal's key.
In some circumstances, a server may only wish to change its key in the local key storage, and not in the DCE Registry. For example, a database system may have several replicas of a master database, managed by servers running on independent machines. Since these servers together represent only one service, they should all share the same key. This way, a user with a ticket to use the database can choose whichever server is least busy. To change the database key, the master server would signal all the replica (slave) servers to change the current key in their local key storage. They would use the sec_key_mgmt_set_key( ) routine, which does not communicate with the DCE Registry. Once all the slaves have complied, the master server can then change the Registry key and its own local storage.
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.
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_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.
error_status_ok
The call was successful.
Related Information
Functions:
sec_key_mgmt_gen_rand_key(3sec)