rpc_mgmt_inq_server_princ_name(3rpc)
Returns a server's principal name
Used by client, server, or management applications.
Synopsis
#include <dce/rpc.h>
void rpc_mgmt_inq_server_princ_name(
rpc_binding_handle_t binding,
unsigned32 authn_svc,
unsigned_char_t **server_princ_name,
unsigned32 *status);
Parameters
Input
binding
Specifies a binding handle. If a client application wants the principal name from a server application, supply a server binding handle for that server. For a server
application to receive a principal name of itself, supply the value NULL.
If the binding handle you supply refers to partially bound binding information and the binding information contains a nil object UUID, this routine returns the rpc_s_binding_incomplete status code. In this case the DCE host daemon does not know which server instance to select from the local endpoint map because the RPC runtime automatically registers the RPC management interface for all RPC servers.
You can avoid this situation by calling rpc_ep_resolve_binding( ) to obtain a fully bound server binding handle.
authn_svc
Specifies the authentication service for which a principal name is returned. The rpc_binding_set_auth_info(3rpc) reference page, in its explanation of the
authn_svc parameter, contains a list of supported authentication services.
Output
server_princ_name
Returns a principal name. This name is registered for the authentication service in parameter authn_svc by the server referenced in parameter
binding. If the server registered multiple principal names, only one of them is returned.
status
Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not.
In addition to the above values, status can return the value of parameter status from the application-defined authorization function (rpc_mgmt_authorization_fn_t). The prototype for such a function is defined in the authorization_fn parameter in the reference page for rpc_mgmt_set_authorization_fn(3rpc).
Description
An application calls the rpc_mgmt_inq_server_princ_name( ) routine to obtain the principal name of a server registered for a specified authentication
service.
A client (or management) application uses this routine when it wants to allow one-way authentication with the server specified by binding. This means that the client does not care which server principal receives the remote procedure call request. However, the server verifies that the client is who the client claims to be. For one-way authentication, a client calls this routine before calling rpc_binding_set_auth_info( ).
A server application uses this routine to obtain the principal name it registered by calling rpc_server_register_auth_info( ).
The RPC runtime allocates memory for the string returned in server_princ_name. The application calls rpc_string_free( ) to deallocate that memory.
By default, the RPC runtime allows all clients to call this routine remotely. To restrict these calls, a server application supplies an authorization function by calling rpc_mgmt_set_authorization_fn( ).
Return Values
No value is returned.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
rpc_s_ok
Success.
rpc_s_binding_incomplete
Binding incomplete (no object ID and no endpoint).
rpc_s_comm_failure
Communications failure.
rpc_s_mgmt_op_disallowed
Management operation disallowed.
rpc_s_unknown_authn_service
Unknown authentication service.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
Related Information
Functions: rpc_binding_inq_object(3rpc)
rpc_binding_set_auth_info(3rpc)
rpc_mgmt_set_authorization_fn(3rpc)
rpc_server_register_auth_info(3rpc)