NAME
dced_intro - Introduction to the DCE Host daemon routines
DESCRIPTION
This introduces the DCE Host Daemon application programming interface:
the dced API. This API gives management applications remote access to
various data, servers, and services on DCE hosts. Servers manage their
own configuration in the local dced by using the routines starting with
dce_server, introduced in the dce_server_intro reference page.
THE DCED API NAMING CONVENTIONS
All of the dced API routine names begin with the dced_ prefix. This
API contains some specialized routines that operate on services
represented by the following keywords in the routine names:
hostdata The host data management service stores host-specific data
such as the host name, the host's cell name, and other data,
and it provides access to these data items.
server The server control service configures, starts, and stops
servers, among other things. Applications must distinguish
two general states of server control: server configuration
(srvrconf) and server execution (srvrexec).
secval The security validation service maintains a host's principal
identity and ensures applications that the DCE Security
daemon is genuine.
keytab The key table management service remotely manages key tables.
The dced also provides the endpoint mapper service which has
its own API, described with the RPC API. These routines
begin with rpc_ep and rpc_mgmt_ep.
Since some of the dced daemon's services require the same operations
(but on different data types), the dced API also contains generic
routines that may operate on more than one of the above services.
For example, you use the routine dced_object_read() to read a data
item (object) from the hostdata, srvrconf, srvrexec, or keytab services.
FILES
dce/dced_base.h
dce/dced.h
dce/dced_data.h
dce/rpctypes.idl
dce/passwd.idl
dce/sec_attr_base.idl
RELATED INFORMATION
ROUTINES: dced_* API.
BOOKS: OSF DCE Application Development Guide
1 – Dced Binding Routines
A binding must be established to a dced service on a particular host
before you can use any other dced routines. The resources of the
dced binding should also be released when an application is finished
with the service.
dced_binding_create Establishes a dced binding to a host service
dced_binding_from_rpc_binding
Establishes a dced binding to a dced service on
the host specified in an already-established RPC
binding handle to any server
dced_binding_set_auth_info
Sets authentication, authorization, and
protection level information for a dced binding
handle
dced_binding_free Releases the resources of a dced binding handle
1.1 – dced_binding_create
NAME
dced_binding_create - Establishes a dced binding to one of the
host services of a remote (or the local) dced.
SYNOPSIS
#include <dce/dced.h>
void dced_binding_create( dced_string_t service,
unsigned32 binding_flags,
dced_binding_handle_t *dced_bh,
error_status_t *status );
PARAMETERS
Input
service
A character string that specifies a host daemon service name
and an optional remote host. A service name is specified with
one of the following: hostdata, srvrconf, srvrexec, secval, or
keytab. The format of a complete service and host specification
is one of the following:
service_name
A service at the local host. Pre-existing defined
values include:
dced_c_service_hostdata
dced_c_service_srvrconf
dced_c_service_srvrexec
dced_c_service_secval
dced_c_service_keytab
service_name@hosts/host_name
A service at a host anywhere in the local namespace.
/.:/hosts/host_name/config/service_name
A complete specification for service_name@host, where
the host is anywhere in the local namespace.
/.../cell/hosts/host_name/config/service_name
A service at a host anywhere in the global namespace.
binding_flags
Currently, the only valid flag value is
dced_c_binding_syntax_default.
Output
dced_bh
Returns a dced binding handle which is a pointer to an opaque
data structure containing information about an RPC binding, the
host, the host service, and a local cache.
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
dce_cf_e_no_mem
dced_s_invalid_arg
dced_s_no_memory
dced_s_unknown_service
rpc_s_entry_not_found
rpc_s_incomplete_name
rpc_s_invalid_object
rpc_s_name_service_unavailable
rpc_s_no_memory
rpc_s_no_more_bindings
rpc_s_no_ns_permission
DESCRIPTION
The dced on each DCE host maintains the host services and provides
a remote interface to them. The host services include the
following:
+ Endpoint Mapper
+ Host Data Management (hostdata)
+ Server Management: Including Server Configuration (srvrconf)
and Server Execution (srvrexec)
+ Security Validation (secval)
+ Key Table Management (keytab)
The dced_binding_create() routine establishes a dced binding to a
dced service and it (or dced_binding_from_rpc_binding()) must be the
first dced API routine called before an application can access one
of the host services with other dced API routines. When an
application is finished with the service, it should call the
dced_binding_free() routine to free resources. To establish a dced
binding to your local host's dced, you can use the service name by
itself, and do not need to specify a host.
To access the endpoint map directly, use rpc_mgmt_ep_elt_inq_begin()
and associated routines.
EXAMPLES
This example establishes a dced binding to the server configuration
service on the host patrick.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_binding_create("srvrconf@hosts/patrick",
dced_c_binding_syntax_default,
&dced_bh,
&status);
.
. /* Other routines including dced API routines. */
.
dced_binding_free(dced_bh, &status);
RELATED INFORMATION
Routines: dced_binding_free
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
1.2 – dced_binding_from_rpc_binding
NAME
dced_binding_from_rpc_binding - Establishes a dced binding to one
of the host services on the host
specified in an existing RPC binding
handle.
SYNOPSIS
#include <dce/dced.h>
void dced_binding_from_rpc_binding( dced_service_type_t service,
handle_t rpc_bh,
dced_binding_handle_t *dced_bh,
error_status_t *status );
PARAMETERS
Input
service
A variable that specifies one of the host services. A valid
variable name includes one of the following:
dced_e_service_type_hostdata
dced_e_service_type_srvrconf
dced_e_service_type_srvrexec
dced_e_service_type_secval
dced_e_service_type_keytab
rpc_bh
An RPC binding handle to some server.
Output
dced_bh
Returns a dced binding handle which is a pointer to an opaque
data structure containing information about an RPC binding, the
host, the host service, and a local cache.
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_memory
dced_s_unknown_service
ept_s_cant_perform_op
ept_s_database_invalid
ept_s_invalid_context
ept_s_invalid_entry
rpc_s_comm_failure
rpc_s_fault_context_mismatch
rpc_s_invalid_arg
rpc_s_invalid_binding
rpc_s_no_more_elements
rpc_s_wrong_kind_of_binding
DESCRIPTION
The dced on each DCE host maintains the host services and provides
a remote interface to the services. The
dced_binding_from_rpc_binding() routine establishes a dced binding
to a dced service, and it (or dced_binding_create()) must be the
first dced API routine called before an application can access one
of the host services with other dced routines. When an application
is finished with the service, it should call the dced_binding_free()
routine to free resources.
Prior to using the RPC binding in this routine, make a copy of the
binding by using the rpc_binding_copy() routine. This is necessary
if the application needs to continue using the RPC binding because
otherwise the dced binding takes over the RPC binding.
The RPC binding may be obtained from a call to specific RPC
runtime routines such as rpc_binding_from_string_binding,
rpc_ns_binding_import_next, or rpc_ns_binding_lookup_next.
EXAMPLES
This example obtains an RPC binding from a string binding,
and it later makes a copy of the RPC binding for use in the
dced_binding_from_rpc_binding() call.
handle_t rpc_bh, binding_handle;
dced_binding_handle_t dced_bh;
dced_service_type_t service_type;
error_status_t status;
unsigned_char_t string_binding[STRINGLEN];
.
.
.
rpc_binding_from_string_binding( string_binding,
&binding_handle,
&status );
.
.
.
rpc_binding_copy( binding_handle, &rpc_bh, &status );
dced_binding_from_rpc_binding( service_type,
rpc_bh,
&dced_bh,
&status );
.
. /* Other routines including dced API routines. */
.
dced_binding_free(dced_bh, &status);
RELATED INFORMATION
Routines: dced_binding_free
dced_binding_create
rpc_ns_binding_import_next
rpc_ns_binding_lookup_next
rpc_binding_from_string_binding
rpc_binding_copy
Books: OSF DCE Application Development Guide.
1.3 – dced_binding_set_auth_info
NAME
dced_binding_set_auth_info - Sets authentication and authorization
information for a dced binding handle
SYNOPSIS
#include <dce/dced.h>
void dced_binding_set_auth_info(
dced_binding_handle_t dced_bh,
unsigned32 protect_level,
unsigned32 authn_service,
rpc_auth_identity_handle_t authn_identity,
unsigned32 authz_service,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for which to set the
authentication and authorization information.
protect_level
Specifies the protection level for dced API calls that will
use the dced binding handle dced_bh.
authn_service
Specifies the authentication service to use for dced API calls
that will use the dced binding handle dced_bh.
authn_identity
Specifies a handle for the data structure that contains the
calling application's authentication and authorization
credentials appropriate for the selected authn_service and
authz_service services. Specify NULL to use the default
security login context for the current address space.
authz_service
Specifies the authorization service to be implemented by dced
for the host service accessed.
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
ept_s_not_registered
rpc_s_authn_authz_mismatch
rpc_s_binding_incomplete
rpc_s_comm_failure
rpc_s_invalid_binding
rpc_s_mgmt_op_disallowed
rpc_s_rpcd_comm_failure
rpc_s_unknown_authn_service
rpc_s_unsupported_protect_level
rpc_s_wrong_kind_of_binding
DESCRIPTION
The dced_binding_set_auth_info() routine sets up the dced binding
handle so it can be used for authenticated calls that include
authorization information. The rpc_binding_set_auth_info routine
performs in the same way as this one. See it for details of the
parameters and values. Prior to calling this routine, the
application must have established a valid dced binding handle by
calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
EXAMPLES
This example establishes a dced binding to a host's key table
service, and then it calls dced_binding_set_auth_info() so that
the application is authorized to access remote key tables by using
additional calls to the key table service.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_binding_create( (dced_string_t)"keytab@hosts/patrick",
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_binding_set_auth_info( dced_bh,
rpc_c_protect_level_default,
rpc_c_authn_pkt_privacy,
NULL,
rpc_c_authz_dce,
&status );
.
. /* Other routines including dced API routines. */
.
RELATED INFORMATION
Routines rpc_binding_set_auth_info
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
1.4 – dced_binding_free
NAME
dced_binding_free - Releases the resources associated with a dced
binding handle
SYNOPSIS
#include <dce/dced.h>
void dced_binding_free( dced_binding_handle_t dced_bh,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies a dced binding handle to free for a dced service on a
specific host.
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
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
DESCRIPTION
The dced_binding_free() routine frees resources used by a dced
binding handle and referenced information. Use this routine when
your application is finished with a host service to break the
communication between your application and the dced. The dced
binding handle and referenced information is created with the
dced_binding_create() or dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
2 – Generic Entry Routines
All data maintained by dced is managed as entries. Most of the
services of dced have lists of entries traversed with a cursor that
describe where the actual data is maintained.
dced_entry_add Adds a keytab or hostdata entry
dced_entry_remove Removes a hostdata or keytab data entry from dced
dced_initialize_cursor
Obtains a list of data entries from dced and sets
a cursor at the beginning of the list
dced_entry_get_next Obtains the next data entry from a list of entries
dced_release_cursor Releases the resources associated with a cursor
which traverses a service's list of entries
dced_list_get Returns the list of data entries maintained by
a DCE Host service
dced_list_release Releases the resources of a list of entries
dced_inq_id Obtains the UUID associated with an entry name
dced_inq_name Obtains the name associated with an entry UUID
2.1 – dced_entry_add
NAME
dced_entry_add - Adds a keytab or hostdata entry to a host's dced
for an existing file on that host
SYNOPSIS
#include <dce/dced.h>
void dced_entry_add( dced_binding_handle_t dced_bh,
dced_entry_t *entry,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
Input/Output
entry
Specifies the data entry to add to the service.
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_readonly
db_s_store_failed
dced_s_already_exists
dced_s_bad_binding
dced_s_import_cant_access
dced_s_no_support
rpc_s_binding_has_no_auth
sec_acl_invalid_permission
uuid_s_no_address
DESCRIPTION
The dced_entry_add() routine adds a data entry to a dced service.
The data it refers to must already exist in a file on the dced's
host. You can only add hostdata or keytab entries.
A service's data entries do not contain the actual data. Instead,
they contain a UUID, a name for the entry, a brief description of
the item, and a storage tag that describes the location of the
actual data. In the cases of the hostdata and keytab services,
the data for each entry is stored in a file. The dced uses this
two-level scheme so that it can manipulate different kinds of data
in the same way and so names are independent of local file system
requirements.
The hostdata and keytab services each have their respective routines
to create new data and at the same time, add a new entry to the
appropriate service. These routines are dced_hostdata_create() and
dced_keytab_create().
Prior to calling the dced_entry_add() routine, the application must
have established a valid dced binding handle for the hostdata or
keytab service by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
EXAMPLES
The following example shows how to add a printer configuration
file to the hostdata service. The example creates a dced binding
to the local hostdata service, an entry data structure is filled
in with the storage tag containing the full path of the existing
configuration file, and finally the dced_entry_add() routine is
called.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_entry_t entry;
dced_binding_create( dced_c_service_hostdata,
dced_c_binding_syntax_default,
&dced_bh,
&status );
uuid_create( &(entry.id), &status );
entry.name = (dced_string_t)("NEWERprinter");
entry.description = (dced_string_t)
("Configuration for a new printer.");
entry.storage_tag = (dced_string_t)("/etc/NEWprinter");
dced_entry_add( dced_bh, &entry, &status );
.
.
.
RELATED INFORMATION
Routines: dced_entry_remove
dced_hostdata_create
dced_keytab_create
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
2.2 – dced_entry_remove
NAME
dced_entry_remove - Removes a hostdata or keytab data entry from
a dced service's list of entries
SYNOPSIS
#include <dce/dced.h>
void dced_entry_remove( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
entry_uuid
Specifies the UUID of the entry to be removed from the service.
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_del_failed
db_s_key_not_found
db_s_readonly
dced_s_bad_binding
dced_s_no_support
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_entry_remove() routine removes an entry from the hostdata
or keytab service entry list of dced. It does not remove the actual
data stored in the file, but makes it inaccessible from a remote
host by way of the dced's user interfaces which include the dced
API and the DCE control program, dcecp. Each host service that
maintains data also maintains a list of data entries. A data entry
contains a name, a UUID, a brief description, and a storage tag
indicating the location of the actual data.
To delete both the data and entry for the hostdata, keytab, or
srvrconf services use dced_hostdata_delete(), dced_keytab_delete(),
or dced_server_delete(), respectively. (The srvrexec service is
maintained only be dced and the secval service does not maintain
data, so you cannot remove data for these services.)
Applications commonly obtain an entry by traversing the entry list
using the dced_entry_get_next() routine with its associated cursor
routines.
Prior to calling the dced_entry_remove() routine, the application
must have established a valid dced binding handle to the hostdata
or keytab service by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_hostdata_delete
dced_keytab_delete
dced_server_delete
dced_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
2.3 – dced_initialize_cursor
NAME
dced_initialize_cursor - Sets a cursor to the start of a cached
list of data entries for a dced service
SYNOPSIS
#include <dce/dced.h>
void dced_initialize_cursor( dced_binding_handle_t dced_bh,
dced_cursor_t *cursor,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
Output
cursor
Returns the cursor used to traverse the list of data entries,
one at a time. The cursor is an opaque data structure that is
used to keep track of the entries between invocations of the
dced_entry_get_next() routine.
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_iter_not_allowed
db_s_key_not_found
dced_s_bad_binding
dced_s_no_memory
dced_s_no_support
sec_acl_invalid_permission
DESCRIPTION
The dced_initialize_cursor() routine sets a cursor at the start of
a DCE host service's list of data entries. The cursor is then used
in subsequent calls to dced_entry_get_next() to obtain individual
data entries. When the application is finished traversing the
entry list, it should call dced_release_cursor() to free the
resources allocated for the cursor.
The valid services for this routine that have entry lists include
hostdata, srvrconf, srvrexec, and keytab.
If a service's entry list is small, it may be more efficient to
obtain the entire list using the dced_list_get() routine rather
than using cursor routines. This is because dced_list_get()
guarantees the list is obtained with one remote procedure call.
However, your application is scalable if you use the cursor
routines because if an entry list is very large, it may be more
efficient (or even necessary) to obtain the list in chunks with
more than one remote procedure call.
Prior to calling the dced_initialize_cursor() routine, the
application must have established a valid dced binding handle
by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_entry_get_next
dced_release_cursor
dced_list_get
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
2.4 – dced_entry_get_next
NAME
dced_entry_get_next - Obtains one data entry from a list of entries
of a dced service
SYNOPSIS
#include <dce/dced.h>
void dced_entry_get_next( dced_cursor_t cursor,
dced_entry_t **entry,
error_status_t *status );
PARAMETERS
Input/Output
cursor
Specifies the entry list's cursor that points to an entry, and
returns the cursor advanced to the next entry in the list.
Output
entry
Returns a pointer to an entry.
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_entry_get_next() routine obtains a pointer to a data entry,
and advances the cursor to the next entry in the list. This routine
is commonly used in a loop to traverse a host service's entry list.
The data is obtained in an undetermined order. Prior to using this
routine, the application must call dced_initialize_cursor() to
obtain a list of entries and to establish the beginning of the
cursor. When the application is finished traversing the entry
list, it should call dced_release_cursor() to release resources.
A data entry does not contain the actual data, but it contains the
name, identity, description, and storage location of the data. In
the cases of hostdata and keytab services, the data for each entry
is stored in a file. In the cases of srvrconf and srvrexec
services, data is stored in memory. The dced uses this two-level
scheme so that it can manipulate different kinds of data in the same
way.
Prior to using the dced_entry_get_next() routine, the application
must have established a valid dced binding handle by calling either
the dced_binding_create() or dced_binding_from_rpc_binding()
routine.
EXAMPLES
In the following example, a dced binding is obtained from a service
type and an existing rpc binding handle. After establishing an
entry list cursor, the dced_entry_get_next() routine obtains an
entry, one at a time, and the name and description of each entry is
displayed until the entry list is exhausted.
dced_binding_from_rpc_binding( service_type,
rpc_bh,
&dced_bh,
&status );
dced_initialize_cursor( dced_bh, &cursor, &status );
for( ; ; ) { /* forever loop */
dced_entry_get_next( cursor, &entry, &status );
if (status != error_status_ok) break;
display(entry->name, entry->description); /* app. specific */
}
dced_release_cursor( &cursor, &status );
dced_binding_free( dced_bh, &status );
RELATED INFORMATION
Routines: dced_initialize_cursor
dced_release_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
2.5 – dced_release_cursor
NAME
dced_release_cursor - Releases the resources of a cursor which
traverses a dced service's list of entries
SYNOPSIS
#include <dce/dced.h>
void dced_release_cursor( dced_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 only possible status code is:
error_status_ok
DESCRIPTION
The dced_release_cursor() routine releases the resources of a
cursor initially set by the dced_initilalize_cursor() routine
and used by the dced_entry_get_next() routine.
Prior to calling this routine, the application must have first
established a valid dced binding handle by calling either the
dced_binding_create() or dced_binding_from_rpc_binding() routine,
and then the application must have called the
dced_initialize_cursor() routine.
RELATED INFORMATION
Routines: dced_initialize_cursor
dced_entry_get_next
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
2.6 – dced_list_get
NAME
dced_list_get - Returns the list of data entries maintained by a
dced service on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_list_get( dced_binding_handle_t dced_bh,
dced_entry_list_t *list,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
Output
list
Returns a list of data entries for the service.
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_memory
dced_s_no_support
sec_acl_invalid_permission
DESCRIPTION
The dced_list_get() routine obtains all the data entries for a dced
service on a specific host. The list of data entries obtained is not
the actual data. Each entry contains a UUID, name, description, and
storage tag that describes where the data is located (for example, a
file name or memory location). Call the dced_list_release() routine
when your application is finished with the entry list to release
resources allocated with dced_list_get() routine.
If a service's entry list is small, it may be efficient to obtain
the entire list using the dced_list_get() routine because it
guarantees the list is obtained with one remote procedure call.
However, to make your application scalable, use the
dced_initialize_cursor(), dced_entry_get_next(), and
dced_release_cursor() set of routines because if an entry list is
very large, it may be more efficient (or even necessary) to obtain
the list in chunks with more than one remote procedure call.
Prior to calling this routine, the application must have
established a valid dced binding handle by calling either the
dced_binding_create() or dced_binding_from_rpc_binding() routine.
EXAMPLES
In the following example, a dced binding is obtained from a
service type and an existing rpc binding handle. The list of
entries for the service is obtained with the dced_list_get()
routine and each entry's name and description are displayed.
dced_binding_from_rpc_binding( service_type,
rpc_bh,
&dced_bh,
&status );
dced_list_get( dced_bh, &entries, &status );
for(i=0; i<entries.count; i++)
display(&entries); /* application specific */
dced_list_release( dced_bh, &entries, &status );
dced_binding_free( dced_bh, &status );
RELATED INFORMATION
Routines: dced_list_release
dced_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
2.7 – dced_list_release
NAME
dced_list_release - Releases the resources for a list of entries
of a dced service
SYNOPSIS
#include <dce/dced.h>
void dced_list_release( dced_binding_handle_t dced_bh,
dced_entry_list_t *list,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
InputOutput
list
Specifies a list of data entries for the service.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The only possible status code is:
error_status_ok
DESCRIPTION
The dced_list_release() routine releases the resources allocated for
a list of data entries previously retrieved by the dced_list_get()
routine.
Prior to calling this routine, the application must have first
established a valid dced binding handle by calling either the
dced_binding_create() or dced_binding_from_rpc_binding() routine,
and then the application must have called the dced_list_get()
routine.
RELATED INFORMATION
Routines: dced_list_get
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
2.8 – dced_inq_id
NAME
dced_inq_id - Obtains the entry UUID that dced associates with
a name
SYNOPSIS
#include <dce/dced.h>
void dced_inq_id( dced_binding_handle_t dced_bh,
dced_string_t name,
uuid_t *uuid,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
name
Specifies the name for which to obtain the uuid.
Output
uuid
returns the UUID associated with the name input.
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_iter_not_allowed
db_s_key_not_found
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_inq_id() routine obtains the UUID associated with a name
in a service of a specific host's dced. Applications and
administrators use strings maintained by dced to identify data,
but dced and its API must associate each data entry with a UUID.
This routine is valid for the host-data, srvrconf, srvrexec, and
keytab services.
Prior to calling this routine, the application must have
established a valid dced binding handle by calling either the
dced_binding_create() or dced_binding_from_rpc_binding() routine.
EXAMPLES
The following example establishes a dced binding to a host's
server configuration service. The example then obtains the
UUID of some known server in order to read the server's
configuration data.
dced_binding_handle_t dced_bh;
server_t conf;
dced_string_t server_name;
uuid_t srvrconf_id;
error_status_t status;
dced_binding_create( "srvrconf@hosts/patrick",
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_inq_id( dced_bh, server_name, &srvrconf_id, &status );
dced_object_read( dced_bh,
&srvrconf_id,
(void**)&(conf),
&status );
.
.
.
RELATED INFORMATION
Routines: dced_inq_name
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
2.9 – dced_inq_name
NAME
dced_inq_name - Obtains the entry name that dced associates with
a UUID
SYNOPSIS
#include <dce/dced.h>
void dced_inq_name( dced_binding_handle_t dced_bh,
uuid_t *uuid,
dced_string_t *name,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
uuid
Specifies the UUID for which to obtain the name.
Output
name
Returns the name associated with the uuid input.
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_iter_not_allowed
db_s_key_not_found
dced_s_not_found
sec_acl_invalid_permission
uuid_s_bad_version
DESCRIPTION
The dced_inq_name() routine obtains the name associated with a
UUID in a service of a specific host's dced.
A name is a label for each data entry to help applications and
administrators identify all data maintained by dced. The dced
requires UUIDs to keep track of the data it maintains. But it
also maintains a mapping of UUIDs to names so that other
applications and administrators can more easily access the data
by using a recognizable name rather than a cumbersome UUID. A
name is a label for hostdata items, srvrconf and srvrexec servers,
and keytab tables.
Prior to calling this routine, the application must have
established a valid dced binding handle by calling either the
dced_binding_create() or dced_binding_from_rpc_binding() routine.
EXAMPLES
The following example establishes a dced binding handle to the
local host data service, reads an entry, and uses dced_inq_name()
to get the name associated with the attribute ID.
dced_binding_handle_t dced_bh;
uuid_t entry_uuid;
sec_attr_t *data_ptr;
error_status_t status;
.
.
.
dced_binding_create( dced_c_service_hostdata,
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_hostdata_read( dced_bh,
&entry_uuid,
&dced_g_uuid_fileattr,
&data_ptr,
&status );
dced_inq_name( dced_bh,
data_ptr->sec_attr.attr_id,
&name, &status );
.
.
.
RELATED INFORMATION
Routines: dced_inq_id
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
3 – Generic Routines To Read Data Objects
These routines obtain the actual data for items to which entries
refer (objects).
dced_object_read Reads one data item of a dced service, based on
the entry UUID
dced_object_read_all
Reads all the data of a dced service's entry list
dced_objects_release
Releases the resources allocated for data obtained
3.1 – dced_object_read
NAME
dced_object_read - Reads a data item of a dced service on a
specific host
SYNOPSIS
#include <dce/dced.h>
void dced_object_read( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
void **data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
entry_uuid
Specifies the UUID of the dced service's data entry associated
with the data item.
Output
data
Returns the data read. The data returned is one of the
following structures, depending on the service:
Service Data Type Returned
_____________________________
hostdata sec_attr_t
srvrconf server_t
srvrexec server_t
keytab dced_key_list_t
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
dce_cf_e_file_open
dce_cf_e_no_match
dce_cf_e_no_mem
dced_s_bad_binding
dced_s_need_privacy
dced_s_no_memory
dced_s_no_support
dced_s_not_found
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
uuid_s_bad_version
DESCRIPTION
The dced_object_read() routine reads the data for a specified entry
of a dced service. When the application is done with the data, it
should call the dced_objects_release() routine with a value of 1
for the count parameter.
The valid services for which you can read data include hostdata,
srvrconf, srvrexec, and keytab. These host services each have a
list of data entries maintained by dced. The entries do not contain
the actual data but contain the data's identity and an indicator of
the location of the data item. The hostdata service also has the
dced_hostdata_read() routine to read data, and the keytab service
has a series of routines that traverse over the keys in a key table.
(See the dced_keytab_initialize_cursor() routine.) The secval and
endpoint services do not have data items to read with this routine.
Applications can also read the data for all entries of a service
using one call to dced_objects_read_all().
Prior to reading the actual data, an application commonly obtains
the entries to read using the series of cursor routines that begin
with dced_entry_initialize_cursor().
Prior to calling the dced_object_read() routine, the application
must have established a valid dced binding handle by calling either
the dced_binding_create() or dced_binding_from_rpc_binding()
routine.
EXAMPLES
The following example creates a dced binding to a dced service based
on a service type and host in an rpc binding handle. The example
then obtains the service's entry list and reads the data associated
with each entry.
dced_binding_from_rpc_binding( service_type,
rpc_bh,
&dced_bh,
&status );
dced_list_get( dced_bh, &entries, &status );
for(i=0; i<entries.count; i++) {
dced_object_read( dced_bh,
&entries.list[i].id,
&data,
&status );
.
.
.
dced_objects_release( dced_bh, 1, data, &status );
}
.
.
.
RELATED INFORMATION
Routines: dced_objects_release
dced_objects_read_all
dced_hostdata_read
dced_keytab_initialize_cursor
dced_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
3.2 – dced_object_read_all
NAME
dced_object_read_all - Reads all the data for a service of the
DCE Host daemon (dced) on specific host
SYNOPSIS
#include <dce/dced.h>
void dced_object_read_all( dced_binding_handle_t dced_bh,
unsigned32 *count,
void **data_list,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
Output
count
Returns the count of the number of data items read.
data_list
Returns the list of data items read. The data returned is an
array of one of the following types, depending on the service:
Service Data Type of Array Returned
______________________________________
hostdata sec_attr_t
srvrconf server_t
srvrexec server_t
keytab dced_key_list_t
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
dce_cf_e_file_open
dce_cf_e_no_match
dce_cf_e_no_mem
dced_s_bad_binding
dced_s_need_privacy
dced_s_no_memory
dced_s_no_support
dced_s_not_found
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
sec_s_no_memory
uuid_s_bad_version
DESCRIPTION
The dced_object_read_all() routine reads all the data for a
specified host service on a specific host. When the application
is done with the data, it should call the dced_objects_release()
routine. Applications can also read individual data objects for a
service using the dced_object_read() routine.
The valid services for which you can read data include hostdata,
srvrconf, srvrexec, and keytab.
Prior to calling the dced_object_read_all() routine, the application
must have established a valid dced binding handle by calling either
the dced_binding_create() or dced_binding_from_rpc_binding()
routine.
EXAMPLES
The following example reads and displays all the data for a
particular dced service.
dced_binding_handle_t dced_bh;
dced_string_t host_service;
void *data_list;
unsigned32 count;
error_status_t status;
dced_binding_create( host_service,
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_object_read_all( dced_bh, &count, &data_list, &status );
display( host_service, count, &data_list ); /* app. specific */
dced_objects_release( dced_bh, count, data_list, &status );
dced_binding_free( dced_bh, &status );
RELATED INFORMATION
Routines: dced_objects_release
dced_object_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
3.3 – dced_objects_release
NAME
dced_objects_release - Releases the resources allocated for data
read from a dced service
SYNOPSIS
#include <dce/dced.h>
void dced_objects_release( dced_binding_handle_t dced_bh,
unsigned32 count,
void *data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
count
Specifies the number of data items previously read and now to
be released.
Input/Output
data
Specifies the data 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_objects_release() routine releases the resources allocated
when data for dced is read. Applications should call
dced_objects_release() when finished with data allocated by the
following dced API routines:
+ dced_object_read_all()
+ dced_object_read()
+ dced_hostdata_read()
If the data being released was read by using dced_object_read_all(),
the count returned from this routine is used as input to the
dced_objects_release() routine. If the data being released was read
by using dced_object_read() or dced_hostdata_read(), the count value
required as input for the dced_objects_release() routine is 1.
EXAMPLES
In the following example, a binding is created to a dced service
on some host for a service that stores data, and the service's
entry list is obtained. For each entry, the data is read,
displayed, and released.
dced_binding_handle_t dced_bh;
dced_entry_list_t entries;
unsigned32 i;
void *data;
error_status_t status;
dced_binding_create( host_service,
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_list_get( dced_bh, &entries, &status );
for(i=0; i<entries.count; i++) {
dced_object_read( dced_bh,
&(entries.list[i].id),
&data,
&status );
display( host_service, 1, &data ); /* app. specific */
dced_objects_release( dced_bh, 1, data, &status );
.
.
.
RELATED INFORMATION
Routines: dced_object_read
dced_object_read_all
dced_hostdata_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
4 – Host Data Management Routines
dced_hostdata_create
Creates a hostdata item and the associated entry
dced_hostdata_read Reads a hostdata item
dced_hostdata_write Replaces an existing hostdata item
dced_hostdata_delete
Deletes a hostdata item from a specific host and
removes the associated entry
4.1 – dced_hostdata_create
NAME
dced_hostdata_create - Creates a hostdata item and the associated
entry in dced on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_hostdata_create( dced_binding_handle_t dced_bh,
dced_entry_t *entry,
dced_attr_list_t *data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the host data service
on a specific host.
Input/Output
entry
Specifies the hostdata entry to create. You supply a name
(entry->name), description (entry->description), and file
name (entry->storage_tag), in the form of dced strings. You
can supply a UUID (entry->id) for dced to use or you can use
a NULL value and dced will generate a new UUID for the entry.
Input
data
Specifies the data created and written to a file on the host.
The dced_attr_list_t consists of a count of the number of
attributes, and an array of attributes of type sec_attr_t.
The reference OSF implementation has one attribute for a
hostdata item (file contents). However some vendors may
provide multiple attributes.
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_key_not_found
db_s_readonly
db_s_store_failed
dced_s_already_exists
dced_s_bad_binding
dced_s_cant_open_storage_file
dced_s_import_already_exists
dced_s_unknown_attr_type
sec_acl_invalid_permission
DESCRIPTION
The dced_hostdata_create() routine creates a new host data item in
a file on the host to which the dced binding handle refers, and it
generates the associated hostdata entry in the host's dced.
If data that you want to add to the host data service already exists
on the host (in a file), you can add it to the service by calling
dced_entry_add(), which only creates the new data entry for dced.
Prior to calling the dced_hostdata_create() routine, the
application must have established a valid dced binding handle
to the hostdata service by calling either the dced_binding_create()
or dced_binding_from_rpc_binding() routine.
EXAMPLES
The following example creates a binding to the host data service
on the local host, creates the entry data, and fills in the data
structure for one attribute to a hypothetical printer configuration.
The attribute represents a plain-text file containing one string of
data.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_entry_t entry;
dced_attr_list_t data;
int num_strings, str_size;
sec_attr_enc_str_array_t *attr_array;
dced_binding_create( dced_c_service_hostdata,
dced_c_binding_syntax_default,
&dced_bh,
&status );
/*Create an Entry. */
uuid_create(&entry.id, &status);
entry.name = (dced_string_t)("NEWERprinter");
entry.description = (dced_string_t)
("Configuration for a new printer.");
entry.storage_tag = (dced_string_t)("/etc/NEWprinter");
/* create the attributes */
data.count = 1;
num_strings = 1;
data.list = (sec_attr_t *)
malloc( data.count * sizeof(sec_attr_t) );
data.list->attr_id = dced_g_uuid_fileattr;
data.list->attr_value.attr_encoding =
sec_attr_enc_printstring_array;
str_size = sizeof(sec_attr_enc_str_array_t) + num_strings
* sizeof(sec_attr_enc_printstring_p_t);
attr_array = (sec_attr_enc_str_array_t *)malloc(str_size);
data.list->attr_value.tagged_union.string_array = attr_array;
attr_array->num_strings = num_strings;
attr_array->strings[0] = (dced_string_t)
("New printer configuration data");
dced_hostdata_create( dced_bh, &entry, &data, &status );
dced_binding_free( dced_bh, &status );
RELATED INFORMATION
Routines: dced_entry_add
dced_hostdata_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
4.2 – dced_hostdata_read
NAME
dced_hostdata_read - Reads a hostdata item maintained by dced
on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_hostdata_read( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
uuid_t *attr_uuid,
sec_attr_t **data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the hostdata service
on a specific host.
entry_uuid
Specifies the hostdata entry UUID associated with the data
to read.
attr_uuid
Specifies the UUID associated with an attribute of the data.
The attribute is either plain text (dced_g_uuid_fileattr) or
binary (dced_g_uuid_binfileattr). Some vendors may allow other
attributes.
Output
data
Returns the data for the item. See the sec_intro reference
page for details on the sec_attr_t data type.
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
dce_cf_e_file_open
dce_cf_e_no_match
dce_cf_e_no_mem
dced_s_bad_binding
dced_s_cant_open_storage_file
dced_s_invalid_attr_type
dced_s_no_memory
sec_acl_invalid_permission
uuid_s_bad_version
DESCRIPTION
The dced_hostdata_read() routine returns a hostdata item maintained
by dced on a specific host. The standard data items include the
cell name, a list of cell aliases, the host name, a list of UUID-
program pairs (post_processors), and the DCE configuration database,
among other items. For programming convenience, the following
global variables are defined for the entry_uuid of some standard
data items:
dced_g_uuid_cell_name
dced_g_uuid_cell_aliases
dced_g_uuid_host_name
dced_g_uuid_hostdata_post_proc
dced_g_uuid_dce_cf_db
dced_g_uuid_pe_site
dced_g_uuid_svc_routing
Other host-specific data items may also be maintained by the
hostdata service. The UUIDs for these are established when the
data item is created (See dced_hostdata_create()). After the
applications reads host data and when it is done with the data,
it should call the dced_objects_release() routine to release the
resources allocated.
Each hostdata item for a specific host is stored in a local file.
The name of an item's storage file is indicated in the storage tag
field of each dced hostdata entry.
You can also use the dced_object_read() routine to read the text
of a hostdata item. You might use this routine if your application
needs to read data for other host services (srvrconf, srvrexec, or
keytab) in addition to data for the hostdata service.
Prior to calling the dced_hostdata_read() routine, the
application must have established a valid dced binding handle
to the hostdata service by calling either the dced_binding_create()
or dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_objects_release
dced_object_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
4.3 – dced_hostdata_write
NAME
dced_hostdata_write - Replaces an existing hostdata item
maintained by dced on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_hostdata_write( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
dced_attr_list_t *data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the Host Data service
on a specific host.
entry_uuid
Specifies the hostdata entry UUID to associate with the data
to be written.
data
Specifies the data to write. The dced_attr_list_t consists
of a count of the number of attributes, and an array of
attributes of type sec_attr_t. The reference OSF
implementation has one attribute for a hostdata item (file
contents). However some vendors may require multiple
attributes.
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_cant_open_storage_file
dced_s_no_postprocessors
dced_s_postprocessor_file_fail
dced_s_postprocessor_spawn_fail
dced_s_unknown_attr_type
sec_acl_invalid_permission
uuid_s_bad_version
DESCRIPTION
The dced_hostdata_write() routine replaces existing data for a
hostdata item maintained by dced on a specific host. If the
entry_uuid is not one maintained be dced, an error is returned
and a new entry is not created. Use dced_hostdata_create() to
create a new entry.
Prior to calling the dced_hostdata_write() routine, the
application must have established a valid dced binding
handle to the hostdata service by calling either the
dced_binding_create() or dced_binding_from_rpc_binding()
routine.
RELATED INFORMATION
Routines: dced_hostdata_read
dced_hostdata_create
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
4.4 – dced_hostdata_delete
NAME
dced_hostdata_delete - Deletes a hostdata item from a specific
host and removes the associated entry
from dced
SYNOPSIS
#include <dce/dced.h>
void dced_hostdata_delete( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the hostdata service
on a specific host.
entry_uuid
Specifies the UUID of the hostdata entry (and associated data)
to delete.
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_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_hostdata_delete() routine deletes a hostdata item (a file)
from a specific host, and removes the associated entry from the host
data service of that host's dced.
If you want to only make the data inaccessible remotely but not
delete it, use the dced_entry_remove() routine which only removes
the data's hostdata entry.
Prior to calling the dced_hostdata_delete() routine, the
application must have established a valid dced binding handle
for the hostdata service by calling either the
dced_binding_create() or dced_binding_from_rpc_binding()
routine.
WARNINGS
Do not delete the standard hostdata items such as cell_name,
cell_aliases, host_name, post_processors, or dce_cf.db. This
will cause operational problems for the host.
RELATED INFORMATION
Routines: dced_entry_remove
dced_hostdata_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
5 – Server Configuration Control Routines
dced_server_create Creates a DCE server's configuration data
dced_server_modify_attributes
Modifies a DCE server's configuration data
dced_server_delete Deletes a DCE server's configuration data
dced_server_start Starts a DCE-configured server
5.1 – dced_server_create
NAME
dced_server_create - Creates a DCE server's configuration data
for the host's dced
SYNOPSIS
#include <dce/dced.h>
void dced_server_create( dced_binding_handle_t dced_bh,
server_t *conf_data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrconf service on a
specific host.
Input/Output
conf_data
Specifies the configuration data for the server. The dced_intro
reference page describes the server_t structure.
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_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_name_missing
sec_acl_invalid_permission
DESCRIPTION
The dced_server_create() routine creates a server's configuration
data. This routine is used by management installation applications
to remotely (or locally) establish the data used to control how a
DCE server starts. However, it does not create the program or
start it. Since this activity is typically part of a server's
installation, you can also use dcecp's server create operation.
Management applications use the dced_object_read() routine to read
the configuration data.
Prior to calling dced_server_create(), the application must have
established a valid dced binding handle to the srvrconf service
by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
EXAMPLES
The following example shows how to fill in some of the fields of
a server_t structure and then create the configuration in dced.
dced_binding_handle_t dced_bh;
server_t conf;
error_status_t status;
dced_binding_create( "srvrconf@hosts/katharine",
dced_c_binding_syntax_default,
&dced_bh,
&status );
/* setup a server_t structure */
uuid_create(&conf.id, &status);
conf.name = (dced_string_t)"application";
conf.entryname = (dced_string_t)"/.:/development/new_app";
conf.services.count = 1;
/* service_t structure(s) */
conf.services.list = malloc( conf.services.count *
sizeof(service_t) );
rpc_if_inq_id( application_v1_0_c_ifspec,
&(conf.services.list[0].ifspec),
&status );
conf.services.list[0].ifname =
(dced_string_t)"application";
conf.services.list[0].annotation =
(dced_string_t)"A new application";
conf.services.list[0].flags = 0;
/* server_fixedattr_t structure */
conf.fixed.startupflags = server_c_startup_explicit |
server_c_startup_on_failure;
conf.fixed.flags = 0;
conf.fixed.program = (dced_string_t)"/usr/users/bin/new_app";
dced_server_create( dced_bh, &conf, &status );
.
.
.
RELATED INFORMATION
Routines: dced_object_read
dced_binding_create
dced_binding_from_rpc_binding
dcecp objects: server
Books: OSF DCE Application Development Guide.
5.2 – dced_server_modify_attributes
NAME
dced_server_modify_attributes - Modifies attributes for a DCE
server's configuration data
SYNOPSIS
#include <dce/dced.h>
void dced_server_modify_attributes(
dced_binding_handle_t dced_bh,
uuid_t *conf_uuid,
dced_attr_list_t *data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrconf service
on a specific host.
conf_uuid
Specifies the UUID that dced uses to identify a server's
configuration data to be modified.
data
Specifies the attributes to be modified.
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_iter_not_allowed
db_s_readonly
db_s_store_failed
dced_s_bad_binding
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_server_modify_attributes() routine replaces a server's
attributes of its configuration data maintained by dced on a
specific host. This routine is typically called after a
configuration is created with the dced_server_create() routine.
A server's configuration is manipulated in a server_t data
structure, and the dced_server_modify_attributes() routine
affects only the attributes member of this structure. To change
other server configuration data, you must first delete the
configuration by using dced_server_delete() and then create the
configuration again by using dced_server_create().
Prior to calling dced_server_modify_attributes(), the application
must have established a valid dced binding handle to the srvrconf
service by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
RELATED INFORMATION
Routines: dced_object_read
dced_binding_create
dced_binding_from_rpc_binding
dcecp Objects: server
Books: OSF DCE Application Development Guide
5.3 – dced_server_delete
NAME
dced_server_delete - Deletes a DCE server's configuration data
from dced
SYNOPSIS
#include <dce/dced.h>
void dced_server_delete( dced_binding_handle_t dced_bh,
uuid_t *conf_uuid,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrconf service
on a specific host.
conf_uuid
Specifies the UUID that dced uses to identify the server's
configuration data 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
dced_s_bad_binding
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_server_delete() routine deletes a server's configuration
data from the server's dced. This routine removes a server from
DCE control by making it incapable of starting via dced. It does
not delete the program from disk nor does it affect the server
if it is currently running.
Prior to using dced_server_delete(), the server configuration
data must be created by an administrator using the dcecp server
create operation or by an application that using
dced_server_create().
Prior to calling dced_server_delete(), the application must
have established a valid dced binding handle to the srvrconf
service by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
EXAMPLES
In the following example, a dced binding is created to the
server configuration service on a host, and then an inquiry
is made as to the UUID associated with a particular server.
The dced_server_delete() routine is then used to delete the
configuration.
dced_binding_handle_t dced_bh;
dced_string_t server_name;
uuid_t srvrconf_id;
error_status_t status;
name_server( &server_name ); /* application specific */
dced_binding_create( "srvrconf@hosts/katharine",
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_inq_id( dced_bh, server_name, &srvrconf_id, &status );
dced_server_delete( dced_bh, &srvrconf_id, &status );
dced_binding_free( dced_bh, &status );
RELATED INFORMATION
Routines: dced_server_create
dced_server_modify_attributes
dced_binding_create
dced_binding_from_rpc_binding
dcecp Objects: server
Books: OSF DCE Application Development Guide.
5.4 – dced_server_start
NAME
dced_server_start - Starts a DCE-configured server on a
specified host
SYNOPSIS
#include <dce/dced.h>
void dced_server_start( dced_binding_handle_t dced_bh,
uuid_t *conf_uuid,
dced_attr_list_t *attributes,
uuid_t *exec_uuid,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrconf service on a
specific host.
conf_uuid
Specifies the UUID that dced uses to identify the server to
start. If the value input is that of a server that is
already running, dced starts a new instance.
attributes
Specifies the configuration attributes to use to start the
server. If the value is NULL, the default configuration
defined in dced is used.
Input/Output
exec_uuid
Specifies a new UUID for dced to use to identify the running
server. If a NIL UUID is input, a new UUID is created and
returned. If the value input is that of a server that is
already running, dced starts a new instance and returns a
new value.
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_iter_not_allowed
db_s_key_not_found
db_s_readonly
db_s_store_failed
dced_s_bad_binding
dced_s_no_support
dced_s_not_found
dced_s_sc_cant_fork
dced_s_sc_invalid_attr_type
dced_s_sc_open_file_failed
sec_acl_invalid_permission
uuid_s_bad_version
DESCRIPTION
The dced_server_start() routine starts DCE-configured servers on
a specific remote host (or the local host). The configuration
data is stored in an object in the srvrconf service of dced.
When the server starts, dced uses the server configuration object
and creates a server execution object in the srvrexec service.
A server execution object consists of data that describes the
executing server.
Management applications create the configuration data by using
the dced_server_create() use the dced_object_read() routine to
read the configuration or execution data.
Prior to calling dced_server_start(), the application must have
established a valid dced binding handle to the srvrconf service
by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
EXAMPLES
The following example starts a configured server using a nil UUID
as input for the executing server.
dced_binding_handle_t conf_bh;
dced_string_t server_name;
uuid_t srvrconf_id, srvrexec_id;
error_status_t status;
dced_binding_create( "srvrconf@hosts/patrick",
dced_c_binding_syntax_default,
&conf_bh,
&status );
dced_inq_id( conf_bh, server_name, &srvrconf_id, &status );
uuid_create_nil( &srvrexec_id, &status );
dced_server_start( conf_bh,
&srvrconf_id,
NULL,
&srvrexec_id,
&status );
.
.
.
RELATED INFORMATION
Routines: dced_server_create
dced_server_stop
dced_binding_create
dced_binding_from_rpc_binding
Commands: server
Books: OSF DCE Application Development Guide.
6 – Server Execution Control Routines
dced_server_disable_if
Disables a service provided by a server
dced_server_enable_if
Re-enables a service provided by a server
dced_server_stop Stops a DCE-configured server
6.1 – dced_server_disable_if
NAME
dced_server_disable_if - Disables a service (rpc interface)
provided by a specific server on a
specific host
SYNOPSIS
#include <dce/dced.h>
void dced_server_disable_if( dced_binding_handle_t dced_bh,
uuid_t *exec_uuid,
rpc_if_id_t *interface,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrexec service
on a specific host.
exec_uuid
Specifies the UUID that dced uses to identify the running
server.
interface
Specifies the RPC interface identifier that represents the
service to be disabled. The interface identifier is generated
when idl compiles an interface definition file. The interface
identifier is an rpc_if_id_t structure that contains the
interface UUID (uuid) of type uuid_t, and numbers of type
unsigned16 representing the major (vers_major) and minor
(vers_minor) version numbers for the interface.
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_iter_not_allowed
db_s_readonly
db_s_store_failed
dced_s_bad_binding
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_server_disable_if() routine disables a service provided
by a server on a specific host. A service is represented by an
RPC interface identifier. Management applications use this
routine to remotely disable an interface so it is inaccessible by
clients, without completely stopping the entire server.
When a server starts and initializes itself, it must call the
dce_server_register() routine to enable all of its services.
The server can then disable its own individual services by using
dce_server_disable_service(). This routine unregisters the
service's interface from the RPC runtime and marks the interface
as disabled in the endpoint map. As an alternative, a management
application can use dced_server_disable_if() to disable individual
services. However, this routine only affects the endpoint map in
dced by marking the interface as disabled and does not affect the
server's runtime.
A management application can re-enable a service again by calling
the dced_server_enable_if() routine. (Servers re-enable their
own services using the dce_server_enable_if() routine.)
Prior to calling dced_server_disable_if(), the application must
have established a valid dced binding handle to the srvrexec
service by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
RELATED INFORMATION
Routines: dce_server_register
dce_server_disable_if
dce_server_enable_if
dced_server_enable_if
dced_binding_create
dced_binding_from_rpc_binding
dcecp Objects: server
Books: OSF DCE Application Development Guide.
6.2 – dced_server_enable_if
NAME
dced_server_enable_if - Enables a service (rpc interface) of
a specific server on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_server_enable_if( dced_binding_handle_t dced_bh,
uuid_t *exec_uuid,
rpc_if_id_t *interface,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrexec service
on a specific host.
exec_uuid
Specifies the UUID that dced uses to identify the running
server.
interface
Specifies the RPC interface identifier that represents the
service to be enabled. The interface identifier is generated
when idl compiles an interface definition file. The interface
identifier is a structure that contains the interface UUID
(interface->uuid), and the major (interface->vers_major) and
minor (interface->vers_minor) version numbers for the interface.
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_iter_not_allowed
db_s_readonly
db_s_store_failed
dced_s_bad_binding
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_server_enable_if() routine enables a service (or re-enables
a previously disabled service) that a specific server provides.
Management applications use this routine. A service is represented
by an RPC interface identifier.
When a server starts and initializes itself, it typically calls
the dce_server_register() routine to enable all of its services.
The services can then be disabled and re-enabled, as needed. A
server enables and disables its own services by using
dce_server_enable_service() and dce_server_disable_service() and
a management application enables and disables a remote server's
service using dced_server_enable_if() and dced_server_disable_if().
The dce_server* routines affect both the RPC runtime and the local
endpoint map by registering (or unregistering) with the runtime
and setting a flag for the interface in the the endpoint map as
enabled (or disabled). The dced_server_enable_if() and
dced_server_disable_if() routines affect only the remote endpoint
map by setting the flag.
Prior to calling dced_server_enable_if(), the application must
have established a valid dced binding handle to the srvrexec
service by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
RELATED INFORMATION
Routines: dce_server_register
dce_server_enable_if
dce_server_disable_if
dced_server_disable_if
dced_binding_create
dced_binding_from_rpc_binding
dcecp Objects: server
Books: OSF DCE Application Development Guide.
6.3 – dced_server_stop
NAME
dced_server_stop - Stops a DCE-configured server running on a
specific host
SYNOPSIS
#include <dce/dced.h>
void dced_server_stop( dced_binding_handle_t dced_bh,
uuid_t *exec_uuid,
srvrexec_stop_method_t method,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrexec service
on a specific host.
exec_uuid
Specifies a UUID that dced uses to identify the running server.
If the value input is dced_g_uuid_all_servers, then dced
attempts to stop all the DCE servers running on that host.
method
Specifies the method dced uses to stop a server. A method is
represented by one of the following values:
srvrexec_stop_rpc
Uses the rpc_mgmt_stop_server_listening routine.
This is the cleanest way to stop a server
because it waits for outstanding remote procedure
calls to finish before making the server's
rpc_server_listen() routine return.
srvrexec_stop_soft
Uses a "soft" local host mechanism (such as the
TERM signal in UNIX)
srvrexec_stop_hard
Uses a "hard" local host mechanism (such as the
KILL signal in UNIX)
srvrexec_stop_error
Uses a mechanism that saves the program state
(such as the ABORT signal in UNIX)
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
dced_s_not_found
rpc_s_binding_incomplete
rpc_s_comm_failure
rpc_s_invalid_binding
rpc_s_mgmt_op_disallowed
rpc_s_unknown_if
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
uuid_s_bad_version
DESCRIPTION
The dced_server_stop() routine stops DCE-configured servers on
specific hosts. When the server is completely stopped and no
longer a running process, dced deletes the associated execution
data it maintained.
Administrators use the dcecp operations server create and server
start to configure and start a server, and management applications
use the associated dced_server_create() and dced_server_start()
routines.
Prior to calling dced_server_stop(), the application must have
established a valid dced binding handle to the srvrexec service
by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
CAUTIONS
Using the value dced_g_uuid_all_servers for the exec_uuid parameter
causes dced to shutdown all servers including itself.
EXAMPLES
The following example obtains dced binding handles to the server
configuration and execution services of dced on the host patrick.
The example then checks to see if the server is running by seeing
if dced has a UUID and entry for the executing server. However,
the server may be in the process of starting up or stopping, so the
example also checks to be sure the instance UUID of the running
server matches the UUID of the configuration for that server. If
there is a match, the server is running. Finally, the example
stops the server by calling dced_server_stop() with the
srvrexec_stop_rpc parameter.
dced_binding_handle_t conf_bh, exec_bh;
dced_string_t server_name;
void *data;
server_t *exec_ptr;
uuid_t srvrconf_id, srvrexec_id;
error_status_t status;
.
.
.
dced_binding_create( "srvrconf@hosts/patrick",
dced_c_binding_syntax_default,
&conf_bh,
&status );
dced_binding_create( "srvrexec@hosts/patrick",
dced_c_binding_syntax_default,
&exec_bh,
&status) ;
/* is server running? */
dced_inq_id( exec_bh, server_name, &srvrexec_id, &status );
/* also check to be sure server is not coming up or going down */
dced_object_read( exec_bh, &srvrexec_id, &data, &status );
exec_ptr = (server_t*)data;
dced_inq_id( conf_bh, server_name, &srvrconf_id, &status );
if (uuid_equal( &srvrconf_id,
&exec_ptr->exec_data.tagged_union.running_data.instance,
&status) ) {
dced_server_stop( exec_bh,
&srvrexec_id,
srvrexec_stop_rpc,
&status );
}
dced_objects_release( exec_bh, 1, data, &status );
dced_binding_free( conf_bh, &status );
dced_binding_free( exec_bh, &status );
RELATED INFORMATION
Routines: dced_server_create
dced_server_start
rpc_mgmt_stop_server_listening
dced_binding_create
dced_binding_from_rpc_binding
dcecp Objects: server
Books: OSF DCE Application Development Guide.
7 – Security Validation Routines
dced_secval_start Starts a host's security validation service
dced_secval_validate
Validates that the DCE Security daemon (secd)
used by a specific host is legitimate
dced_secval_status Returns a status parameter of TRUE if the
security validation service is activated and
FALSE if not
dced_secval_stop Stops a host's security validation service
7.1 – dced_secval_start
NAME
dced_secval_start - Starts the security validation service of
a specific host's dced
SYNOPSIS
#include <dce/dced.h>
void dced_secval_start( dced_binding_handle_t dced_bh,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the secval service on
a specific host.
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_sv_already_enabled
sec_acl_invalid_permission
DESCRIPTION
The dced_secval_start() routine starts the Security Validation
service of a specific host's dced. This routine is typically
used by management applications.
The Security Validation service (secval) has two major functions:
1. Maintain a login context for the host's self identity.
2. Validate and certify to applications (usually login programs)
that the DCE Security daemon (secd) is legitimate.
The secval is commonly started by default when dced starts.
See the dced_secval_stop() routine for a discussion of when to
use the combination of dced_secval_stop() and dced_secval_start().
Prior to calling this routine, the application must have
established a valid dced binding handle to the secval service
by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_secval_stop
dced_binding_create
dced_binding_from_rpc_binding
Commands: dced
The secval object of dcecp
Books: OSF DCE Application Development Guide.
7.2 – dced_secval_validate
NAME
dced_secval_validate - Validates that the secd used by a
specific host is legitimate
SYNOPSIS
#include <dce/dced.h>
void dced_secval_validate( dced_binding_handle_t dced_bh,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the secval service on
a specific host.
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
ept_s_not_registered
rpc_s_comm_failure
rpc_s_invalid_binding
rpc_s_rpcd_comm_failure
rpc_s_wrong_kind_of_binding
sec_login_s_no_current_context
DESCRIPTION
The dced_secval_validate() routine validates and certifies for
a specific host that the DCE Security daemon (secd) is legitimate.
Typically, a login program uses the security validation service
when it uses the Security Service's Login API (routines that begin
with sec_login). However, if a management application trusts some
remote host, it can use dced_secval_validate() to validate secd,
without logging in to the host.
RELATED INFORMATION
Routines: sec_login* API
dced_secval_start
dced_binding_create
dced_binding_from_rpc_binding
Commands: dced
The secval object of dcecp
Books: OSF DCE Application Development Guide.
7.3 – dced_secval_status
NAME
dced_secval_status - Indicates whether or not a specific host's
security validation service of dced is
running
SYNOPSIS
#include <dce/dced.h>
void dced_secval_status( dced_binding_handle_t dced_bh,
boolean32 *secval_active,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the secval service on
a specific host.
Output
secval_active
Returns a value of TRUE if the security validation service
is running and FALSE if it is not running.
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
DESCRIPTION
The dced_secval_status() routine sets a parameter to TRUE or
FALSE depending on whether the security validation service has
been activated or deactivated.
Prior to calling this routine, the application must have
established a valid dced binding handle to the secval service
by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_secval_start
dced_secval_stop
dced_binding_create
dced_binding_from_rpc_binding
Commands: dced
the secval object of dcecp
Books: OSF DCE Application Development Guide.
7.4 – dced_secval_stop
NAME
dced_secval_stop - Stops the security validation service of
a specific host's dced
SYNOPSIS
#include <dce/dced.h>
void dced_secval_stop( dced_binding_handle_t dced_bh,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the secval service on
a specific host.
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_sv_not_enabled
sec_acl_invalid_permission
DESCRIPTION
The dced_secval_stop() routine stops the security validation service
(secval) of a specific host's dced. This routine is typically used
by managment applications.
The secval service is commonly started by default when dced starts.
The main use of dced_secval_stop() and dced_secval_start() is to
force a refresh of the host principal credentials. This is the only
way to force certain registry changes made by the host principal
(such as groupset membership) to be seen by processes running on the
host.
You can easily stop and then start the secval service with the
following operations:
dcecp -c secval deactivate
dcecp -c secval activate
It is not a good idea to remove the machine principal self
credentials for an extended period of time because processes
running as self will fail in their attempts to perform
authenticated operations.
RELATED INFORMATION
Routines: dced_secval_start
dced_binding_create
dced_binding_from_rpc_binding
Commands: dced
The secval object of dcecp
Books: OSF DCE Application Development Guide.
8 – Key Table Management Routines
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
8.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.
8.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.
8.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.
8.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.
8.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.
8.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.
8.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.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.
9 – Data Types And Structures
The following data types used with the dced API are defined in
dce/dced_base.idl and are shown here in alphabetical order.
dced_attr_list_t
This data structure specifies the configuration attributes to
use when you start a server via dced. The structure consists
of the following:
count An unsigned32 number representing the number of
attributes in the list.
list An array of configuration attributes where each
element is of type sec_attr_t. This data type is
described in the sec_intro reference page.
For dced, the list[i].attr_id field can have values
of either dced_g_uuid_fileattr specifying plain text
or dced_g_uuid_binfileattr specifying binary data.
dced_binding_handle_t
A dced binding handle is an opaque pointer that refers to
information that includes a dced service (hostdata, srvrconf,
srvrexec, secval, or keytab) and RPC binding information for
a specific DCE Host daemon.
dced_cursor_t
The entry list cursor is an opaque pointer used to keep track
of a location in an entry list between calls that traverse the
list.
dced_entry_t
An entry is the structure that contains information about a
data item (or object) maintained by a dced service. The
actual data is maintained elsewhere. Each entry consists of
the following structure members:
id A unique identifer of type uuid_t that dced maintains
for every data item it maintains
name The name for the data item. The data type is
dced_string_t .
description
A brief description the data item (of type
dced_string_t) for the convenience of human users.
storage_tag
A string of type dced_string_t describing the
location of the actual data. This is implementation-
specific and may be a file (with a pathname) on the
host system or a storage identifier for the dced
process.
dced_entry_list_t
An entry list is a uniform way to list the data items a dced
service maintains. The entry list structure contains a list
of all the entries for a given service. For example, the
complete list of all entries of hostdata, server configuration
data, server execution data, and keytab data are each
maintained in separate entry lists. The structure consists of
the following:
count An unsigned32 number representing the number of
entries in the list.
list An array of entries where each element is of type
dced_entry_t.
dced_key_t
A key consists of the following structure members:
principal A dced_string_t type string representing the principal
for the key.
version An unsigned32 number representing the version number
of the key.
authn_service
An unsigned32 number representing the authentication
service used.
passwd A pointer to a password. This is of type
sec_passwd_rec_t .
See also the Security introduction reference page, sec_intro.
dced_key_list_t
A key list contains all the keys for a given key table and
consists of the following structure elements:
count An unsigned32 number representing the number of keys
in the list.
list An array of keys where each element is of type
dced_key_t.
dced_keytab_cursor_t
The keytab cursor is an opaque pointer used to keep track of
a location in a key list between calls that traverse the list.
dced_opnum_list_t
A list of operation numbers is used in the service_t structure.
This structure consists of the following fields:
count An unsigned32 number representing the number of
operations in the list.
list An array of UUIDs where each element is of type
uuid_t.
dced_service_type_t
The dced service type distinguishes the services provided by
dced. It is an enumerated type used mainly in a parameter of
the dced_binding_from_rpc_binding() routine. It can have one
of the following values:
dced_e_service_type_hostdata
The host data management service
dced_e_service_type_srvrconf
The server configuration management service
dced_e_service_type_srvrexec
The server execution management service
dced_e_service_type_secval
The security validation service
dced_e_service_type_keytab
The key table management service
dced_e_service_type_null
A NULL service type used internally
dced_string_t
This data type is a character string from the Portable
Character Set (PCS).
dced_string_list_t
A list of strings with the following format:
count An unsigned32 number representing the number of
strings in the list.
list An array of strings where each element is of type
dced_string_t.
dced_tower_list_t
A list of protocol towers used in the service_t structure.
This structure consists of the following fields:
count An unsigned32 number representing the number of
protocol towers in the list.
list An array of pointers where each element is a
pointer to a protocol tower of the type
sec_attr_twr_set_p_t. This data type is
described in the sec_intro reference page.
server_fixedattr_t
This structure is a field in the server_t structure. It
contains the following fields:
startupflags
This field is of type unsigned32 and can be any
combination of the following bits:
server_c_startup_at_boot
This means that dced should start
the server when dced is started.
server_c_startup_auto
This means that the server can be
started automatically if dced
determines there is a need.
server_c_startup_explicit
This means dced can start the server
if it receives an explicit command to
do so via dced_server_start() or the
dcecp operation server start.
server_c_startup_on_failure
This means that the server should
be restarted by dced if it exits
with an unsuccesful exit status.
Several bits are also reserved for vendor-specific startup and
include server_c_startup_vendor1, server_c_startup_vendor2,
server_c_startup_vendor3, and server_c_startup_vendor4.
flags This represents the execution state of the server and
is the unsigned32 type. This field is maintained only
by dced and should not be modified. Valid values to
check for are self-explanatory and include the
following:
server_c_exec_notrunning
server_c_exec_running
Several bits are also reserved for vendor-specific
execution states and include:
server_c_exec_vendor1
server_c_exec_vendor2
server_c_exec_vendor3
server_c_exec_vendor4
program This is the full path name of the server and is of
type dced_string_t.
arguments This is a list of arguments for the server and is of
type dced_string_list_t.
prerequisites
This is an advisory field that means this server is
a client of other prerequisite servers whose IDs are
in a list of type uuid_list_t. The UUIDs should be
the id fields from the server_t structures of the
relevent servers.
keytables This is a list of keytab entry UUIDs representing
the key tables for this server and is of type
uuid_list_t.
posix_uid This is a POSIX execution attribute for the user ID.
It is of type unsigned32.
posix_gid This is a POSIX execution attribute for the group ID.
It is of type unsigned32.
posix_dir This is a POSIX execution attribute for the directory
in which the server started when it is invoked. It
is of type dced_string_t.
server_t
The DCE Host daemon describes a server as follows:
id Each server has a unique ID of type uuid_t.
name Each server's name is of type dced_string_t.
entryname The server's entry name is a hint as to where the
server appears in the namespace. This is of type
dced_string_t.
services Each server offers a list of services specified in
a list of type service_list_t. This structure has
the following members:
count An unsigned32 number representing the
number of services in the list.
list A pointer to an array of services where
each element is of type service_t.
fixed This is a set of attributes common to all DCE
implementations. The data type is
server_fixedattr_t.
attributes
This field is of type dced_attr_list_t and contains
a list of attributes representing the behavior
specific to a particular server or host.
prin_names
This field is a list of principal names for the
server and is of type dced_string_list_t.
exec_data Data about an executing server is maintained in
a tagged union (named tagged_union) with a
discriminator of type unsigned32 named execstate
representing the server's execution state. The
union has the following two execution states:
server_c_exec_notrunning
For the case where the server is not running,
the union member has no value. For example:
if(server->exec_data.execstate == server_c_exec_no)
server->exec_data.tagged_union = NULL;
server_c_exec_running
For the case where the server is running,
and the value of the union member is a
srvrexec_data_t data type named running_data.
A srvrexec_data_t structure contains the
following members:
instance Each instance of a server on a host
is identified with a UUID
(type uuid_t).
posix_pid Each server has a POSIX process ID
of type unsigned32.
service_t
This structure describes each service offered by a server.
The server_t structure, described earlier, contains an array
of these structures. The service_t structure contains the
following fields:
ifspec An interface specification of type rpc_if_id_t,
generated by an idl compilation of the interface
definition representing the service. This data
type is described in the rpc_intro reference
page.
ifname An interface name of type dced_string_t.
annotation
An annotation about the purpose of the interface
(type dced_string_t). This field is for user
display purposes only.
flags The flag field is of type unsigned32 and currently
has only one bit field defined, service_c_disabled.
If this flag is set, it indicates that the service
is not currently available for the server. Also, the
dced Endpoint Mapper will not map an endpoint to a
disabled service. Several values are also reserved
for vendor-specific use and include
service_c_vendor1, service_c_vendor2,
service_c_vendor3, and service_c_vendor4.
entryname The entry name (type dced_string_t) is a hint as to
where this service appears in the namespace. If the
value is NULL, the value in the entryname field of
the server_t structure is used.
objects This is a list of objects supported by the service.
The list is of type uuid_list_t.
operations
This is a list of operation numbers of type
dced_opnum_list_t. This field is not currently used.
towers This is a list of protocol towers of type
dced_tower_list_t, specifying the endpoints
where this server can be reached.
srvrexec_stop_method_t
The server execution stop method is an enumerated type with
one of the following values:
srvrexec_stop_rpc Stops the running server gracefully by
letting the server complete all out-
standing remote procedure calls. This
causes dced to invoke the
rpc_mgmt_server_stop_listening()
routine in that server.
srvrexec_stop_soft This uses a system-specific mechanism
such as the SIGTERM signal. It stops
the running server with a mechanism that
the server can ignore or intercept in
order to do application-specific cleanup.
srvrexec_stop_hard This uses a system-specific mechanism
such as the SIGKILL signal. It stops
the running server immediately with a
mechanism that the server cannot inter-
cept.
srvrexec_stop_error This uses a system-specific mechanism
such as the SIGABRT signal. The local
operating system captures the server's
state before stopping it, and the server
can also intercept it.
uuid_list_t
A list of UUIDs in the following format:
count An unsigned32 number representing the number of
UUIDs in the list.
list A pointer to an array of UUIDs where each element
is of type uuid_t.