dced_keytab_create Creates a key table with a list of keys in a new
file
dced_keytab_delete Deletes a key table file and removes the
associated entry
dced_keytab_initialize_cursor
Obtains a list of keys from a key table and sets
a cursor at the beginning of the list
dced_keytab_get_next_key
Returns a key from a cached list, and advances
the cursor
dced_keytab_release_cursor
Releases the resources associated with a cursor
that traverses a key table
dced_keytab_add_key Adds a key to a key table
dced_keytab_change_key
Changes a key in both a key table and in the
security registry
dced_keytab_remove_key
Removes a key from a key table
1 – dced_keytab_create
NAME
dced_keytab_create - Creates a key table with a list of keys
(server passwords) in a new file on a
specific host
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_create( dced_binding_handle_t dced_bh,
dced_entry_t *keytab_entry,
dced_key_list_t *keys,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the keytab service on
a specific host.
Input/Output
keytab_entry
Specifies the keytab entry to create for dced.
keys
Specifies the list of keys to be written to the key table file.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes are:
error_status_ok
db_s_bad_header_type
db_s_bad_index_type
db_s_bad_index_type
db_s_iter_not_allowed
db_s_key_not_found
db_s_readonly
db_s_store_failed
dced_s_already_exists
dced_s_bad_binding
dced_s_import_already_exists
dced_s_need_privacy
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_key_unsupported
sec_key_mgmt_e_key_version_exists
sec_key_mgmt_e_unauthorized
uuid_s_bad_version
DESCRIPTION
The dced_keytab_create() routine creates a new key table file on
a specific host, and it generates the associated keytab service
entry in dced. This routine is used by management applications
to remotely create a key table. Servers typically create their
own key table locally using the sec_key_mgmt_set_key routine.
However, if several servers on different hosts share the same
principal, each host requires a local copy of the key table.
If a key table that you want to add to the keytab service already
exists on the host, you can add it to the service by calling
dced_entry_add(). This routine creates a new keytab service
entry by associating the existing key table file with a new UUID
in dced.
Prior to calling the dced_keytab_create() routine, the
application must have established a valid dced binding handle
to the keytab service by calling either the dced_binding_create()
or dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: sec_key_mgmt_set_key
dced_entry_add
dced_binding_from_rpc_binding
dced_binding_create
Books: OSF DCE Application Development Guide.
2 – dced_keytab_delete
NAME
dced_keytab_delete - Deletes a key table file from a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_delete( dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the keytab service on
a specific host.
keytab_uuid
Specifies the UUID of the keytab entry and associated key
table to be deleted.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes are:
error_status_ok
db_s_bad_index_type
db_s_del_failed
db_s_iter_not_allowed
db_s_key_not_found
dced_s_bad_binding
dced_s_cant_remove_storage_file
dced_s_need_privacy
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
DESCRIPTION
The dced_keytab_delete() routine deletes a key table (file) from
a specific host and removes the associated entry from the keytab
service of that host's dced. A key table is a file containing a
list of server keys (passwords). This routine is used by
management applications to remotely delete a key table.
To remove individual keys from a remote key table, use the
dced_keytab_remove_key() routine. If you want to only make
the key table inaccessible remotely (via dced) but not delete
it, use the dced_entry_remove() routine. This routine only
removes the key table's keytab entry from dced.
Prior to calling the dced_keytab_delete() routine, the
application must have established a valid dced binding handle
to the keytab service by calling either the dced_binding_create()
or dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_keytab_remove_key
dced_entry_remove
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
3 – dced_keytab_initialize_cursor
NAME
dced_keytab_initialize_cursor - Obtains a list of keys from a key
table and sets a cursor at the
beginning of the list
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_initialize_cursor(
dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
dced_keytab_cursor_t *cursor,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the keytab service on
a specific host.
keytab_uuid
Specifies the keytab entry dced associates with a key table.
Output
cursor
Returns the cursor that is used to traverse the list of keys.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes are:
error_status_ok
dced_s_bad_binding
dced_s_need_privacy
dced_s_no_memory
dced_s_no_support
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_unauthorized
DESCRIPTION
The dced_keytab_initialize_cursor() routine obtains the complete
list of keys from a remote key table and sets a cursor at the
beginning of the cached list keys. In order to minimize the
security risks of keys exposed to the network, the entire set of
keys are encrypted and transferred in one remote procedure call
rather than individually or in chunks. The cursor is then used in
subsequent calls to dced_keytab_get_next_key() to obtain individual
keys. When the application is finished traversing the key list, it
should call dced_keytab_release_cursor() to release the resources
previously allocated.
Management applications use dced_keytab_initialize_cursor() and
its associated routines to remotely access server keys. Servers
use sec_key_mgmt_initialize_cursor and its associated routines
to manage their own keys locally.
Prior to calling the dced_keytab_initialize_cursor() routine, the
application must have established a valid dced binding handle to
the keytab service by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_keytab_get_next_key
dced_keytab_release_cursor
sec_key_mgmt_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
4 – dced_keytab_get_next_key
NAME
dced_keytab_get_next_key - Returns a key from a cached list,
and advances the cursor in the list
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_get_next_key( dced_keytab_cursor_t cursor,
dced_key_t **key,
error_status_t *status );
PARAMETERS
Input/Output
cursor
Specifies the cursor that points to a key, and returns
the cursor advanced to the next key in the list.
Output
key Returns the current key to which the cursor points.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes are:
error_status_ok
dced_s_no_more_entries
DESCRIPTION
The dced_keytab_get_next_key() routine obtains the current key to
which the key-list cursor points. This routine is commonly used
in a loop to traverse a key table's keys. The keys are returned
in an undetermined order. Prior to using this routine in the loop,
the application must call dced_keytab_initialize_cursor() to obtain
the key list and established the beginning of the cursor. When the
application is finished traversing the key list, it should call
dced_keytab_release_cursor() to release the resources allocated.
Management applications use dced_keytab_get_next_key() to
remotely access a server's individual keys. Servers use
sec_key_mgmt_get_next_key to access their own local keys
individually.
You can also use the dced_object_read() routine to read an entire
key table. You might use dced_object_read() if your application
needs to bind to and read data for other host services (srvrconf,
srvrexec, or hostdata) in addition to data for the keytab service.
RELATED INFORMATION
Routines: dced_keytab_initialize_cursor
dced_keytab_release_cursor
sec_key_mgmt_get_next_key
dced_object_read
Books: OSF DCE Application Development Guide.
5 – dced_keytab_release_cursor
NAME
dced_keytab_release_cursor - Releases the resources of a cursor
that traverses a key table's list
of keys (server passwords)
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_release_cursor( dced_keytab_cursor_t *cursor,
error_status_t *status );
PARAMETERS
Input/Output
cursor
Specifies the cursor for which resources are released.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes are:
error_status_ok
dced_s_bad_binding
dced_s_no_support
DESCRIPTION
The dced_keytab_release_cursor() routine releases the cursor and
resources initially set by the dced_keytab_initialize_cursor()
routine and used by the dced_keytab_get_next_key() routine.
Prior to calling this routine, the application must have first
established a valid dced binding handle by calling either
dced_binding_create() or dced_binding_from_rpc_binding(), and
then the application must have called the
dced_keytab_initialize_cursor() routine.
RELATED INFORMATION
Routines: dced_keytab_initialize_cursor
dced_keytab_get_next_key
Books: OSF DCE Application Development Guide.
6 – dced_keytab_add_key
NAME
dced_keytab_add_key - Adds a key (server password) to a specified
key table on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_add_key( dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
dced_key_t *key,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the keytab service
on a specific host.
keytab_uuid
Specifies the UUID that dced uses to identify the key table
to which the key is to be added.
Input/Output
key Specifies the key to be added. Some fields are completed
by dced. See dced_intro.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes are:
error_status_ok
db_s_bad_index_type
db_s_key_not_found
dced_s_bad_binding
dced_s_key_v0_not_allowe
dced_s_key_version_mismatch
dced_s_need_privacy
dced_s_random_key_not_allowed
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_key_unsupported
sec_key_mgmt_e_key_version_exists
sec_key_mgmt_e_unauthorized
DESCRIPTION
The dced_keytab_add_key() routine adds a key to a server's key
table (file) on a specific host, without changing the key in the
security registry. (Servers use sec_key_mgmt_set_key to do this
for their own local key table.)
Most management applications use the dced_keytab_change_key()
routine to remotely change a key because it also changes the key
in the Security Registry.
Managing the same key in multiple key tables is a more complex
process. The Security Registry needs a copy of a server's key so
that during the authentication process, it can encrypt tickets
that only a server with that key can later decrypt. Part of
updating a key in the Security Registry also includes automatic
version number updating. When servers share the same principle
identity they use the same key. If these servers are on different
hosts, then the key must be in more than one key table. (Even if
the servers are on the same host, it is possible for their keys to
be in different key tables, although this is not a recommended key
management practice.) When the same keys in different tables need
changing, one (perhaps the master server or busiest one) is changed
using dced_keytab_change_key() which also causes an automatic
version update. However, all other copies of the key must be
changed using the dced_keytab_add_key() routine so that the version
number does not change again.
Prior to calling dced_keytab_add_key() the application must have
established a valid dced binding handle to the keytab service by
calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_keytab_change_key
sec_key_mgmt_set_key
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
7 – dced_keytab_change_key
NAME
dced_keytab_change_key - Changes a key (server password) in both
a key table and in the security registry
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_change_key( dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
dced_key_t *key,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the keytab service
on a specific host.
keytab_uuid
Specifies the UUID dced uses to identify the key table in
which the key is to be changed.
Input/Output
key Specifies the new key. Some fields are modified by dced.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes are:
error_status_ok
db_s_bad_index_type
db_s_key_not_found
dced_s_bad_binding
dced_s_key_version_mismatch
dced_s_need_privacy
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_authn_unavailable
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_key_unsupported
sec_key_mgmt_e_key_version_exists
sec_key_mgmt_e_not_implemented
sec_key_mgmt_e_unauthorized
sec_rgy_object_not_found
sec_rgy_server_unavailable
DESCRIPTION
The dced_keytab_change_key() routine updates a key in both the key
table on a specific host and in the Security Registry. Management
applications change keys remotely with this routine. (Servers can
change their own keys locally with the sec_key_mgmt_change_key
routine.)
The Security Registry needs a copy of a server's current key so
that during the authentication process, it can encrypt tickets that
only a server with that key can later decrypt. When a management
application calls dced_keytab_change_key(), dced first tries to make
the modification in the Security Registry, and, if successful it
then modifies the key in the key table. The old key is not really
replaced but a new version and key is established for all new
authenticated communication. The old version is maintained in the
key table (and Registry too) for a time so that existing clients
with valid tickets can still communicate with the server. The old
key is removed depending on the local cell's change policy and if
the server calls sec_key_mgmt_garbage_collect() to purge its old
keys explicitly, or sec_key_mgmt_manage_key() to purge them
implicitly.
When more than one server shares the same principal identity, they
use the same key. If you need to change the same key in more than
one key table, use decd_keytab_change_key() for one change and then
use the dced_keytab_add_key() routine for all others.
RELATED INFORMATION
Routines: dced_keytab_add_key
sec_key_mgmt_change_key
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8 – dced_keytab_remove_key
NAME
dced_keytab_remove_key - Removes a key (server password) from a
specified key table on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_remove_key( dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
dced_key_t *key,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the keytab service
on a specific host.
keytab_uuid
Specifies the UUID dced maintains to identify the key table
from which the key is to be removed.
key Specifies the key to be removed from the key table.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes are:
error_status_ok
db_s_bad_index_type
db_s_key_not_found
dced_s_bad_binding
dced_s_need_privacy
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_unauthorized
DESCRIPTION
The dced_keytab_remove_key() routine removes a key from a key
table (file) on a specific host. The key table is specified
with a keytab entry UUID from the host's dced. Management
applications use dced_keytab_remove_key() to remotely remove
server keys from key tables. Typically, servers delete their
own keys from their local key tables implicitly by calling
sec_key_mgmt_manage_key, or explicitly by calling
sec_key_mgmt_delete_key. Applications can delete an entire
key table file using the dced_keytab_delete() routine.
Prior to calling this routine, the application must have
established a valid dced binding handle to the keytab service
by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: sec_key_mgmt_delete_key
dced_keytab_delete
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.