NAME
rpc_binding_set_auth_info - Sets authentication and authorization
information for a server binding handle
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
#include <dce/sec_login.h>
void rpc_binding_set_auth_info(
rpc_binding_handle_t binding,
unsigned_char_t *server_princ_name,
unsigned32 protect_level,
unsigned32 authn_svc,
rpc_auth_identity_handle_t auth_identity,
unsigned32 authz_svc,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies the server binding handle for which to set the
authentication and authorization information.
server_princ_name
Specifies the principal name of the server referenced by binding.
The content of the name and its syntax is defined by the
authentication service in use.
A client that does not know the server principal name can call
the rpc_mgmt_inq_server_princ_name() routine to obtain the
principal name of a server that is registered for the required
authentication service. Using a principal name obtained in this
way means that the client is interested in one-way authentication.
In other words, it means that the client does not care which
server principal received the remote procedure call request. The
server, though, still verifies that the client is who the client
claims to be.
protect_level
Specifies the protection level for remote procedure calls made
using binding. The protection level determines the degree to
which authenticated communications between the client and the
server are protected by the authentication service specified by
authn_svc.
If the RPC runtime or the RPC protocol in the bound protocol
sequence does not support a specified level, the level is
automatically upgraded to the next higher supported level.
The possible protection levels are as follows:
rpc_c_protect_level_default
Uses the default protection level for the specified
authentication service. The default protection
level for the DCE shared-secret key authentication
service is rpc_c_protect_level_pkt_integ.
rpc_c_protect_level_none
Performs no authentication: tickets are not
exchanged, session keys are not established, client
PACs or names are not certified, and transmissions
are in the clear. Note that although uncertified
PACs should not be trusted, they may be useful for
debugging, tracing, and measurement purposes.
rpc_c_protect_level_connect
Performs protection only when the client establishes
a relationship with the server.
rpc_c_protect_level_call
Performs protection only at the beginning of each
remote procedure call when the server receives the
request. This level does not apply to remote
procedure calls made over a connection-based
protocol sequence (that is, ncacn_ip_tcp). If this
level is specified and the binding handle uses a
connection-based protocol sequence, the routine uses
the rpc_c_protect_level_pkt level instead.
rpc_c_protect_level_pkt
Ensures that all data received is from the expected
client.
rpc_c_protect_level_pkt_integ
Ensures and verifies that none of the data
transferred between client and server has been
modified. This is the highest protection level that
is guaranteed to be present in the RPC runtime.
rpc_c_protect_level_pkt_privacy
Performs protection as specified by all of the
previous levels and also encrypt each remote
procedure call argument value. This is the highest
protection level, but it may not be available in
the RPC runtime.
authn_svc
Specifies the authentication service to use. The exact level of
protection provided by the authentication service is specified
by the protect_level parameter. The supported authentication
services are as follows:
rpc_c_authn_none
No authentication: no tickets are exchanged, no
session keys established, client PACs or names are
not transmitted, and transmissions are in the clear.
Specify rpc_c_authn_none to turn authentication off
for remote procedure calls made using binding.
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_default
DCE default authentication service. The current
default authentication service is DCE shared-secret
key; therefore, specifying rpc_c_authn_default is
equivalent to specifying rpc_c_authn_dce_secret.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
rpc_c_authn_winnt
Authentication via Microsoft NT Lan Manager (only
available on Windows NT and OpenVMS). This allows
OpenVMS applications to authenticate with a Windows
NT domain security server.
auth_identity
Specifies a handle for the data structure that contains the
client's authentication and authorization credentials
appropriate for the selected authentication and authorization
services. When using the rpc_c_authn_dce_secret authentication
service and any authorization service, this value must be a
sec_login_handle_t obtained from one of the following routines:
+ sec_login_setup_identity()
+ sec_login_get_current_context()
+ sec_login_newgroups()
+ rpc_winnt_set_auth_identity
Specify NULL to use the default security login context for the current
address space.
authz_svc
Specifies the authorization service implemented by the server
for the interface of interest. The validity and trustworthiness
of authorization data, like any application data, is dependent on
the authentication service and protection level specified. The
supported authorization services are as follows:
rpc_c_authz_none
Server performs no authorization. This is valid only if
the authn_svc parameter is rpc_c_authn_none, specifying
that no authentication is being performed.
rpc_c_authz_name
Server performs authorization based on the client
principal name. This value cannot be used if authn_svc
is rpc_c_authn_none.
rpc_c_authz_dce
Server performs authorization using the client's DCE
Privilege Attribute Certificate (PAC) sent to the
server with each remote procedure call made with
binding. Generally, access is checked against DCE
Access Control Lists (ACLs). This value cannot be
used if authn_svc is rpc_c_authn_none.
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 and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
rpc_s_unknown_authn_service
Unknown authentication service.
rpc_s_authn_authz_mismatch
Requested authorization service is not supported by
the requested authentication service.
rpc_s_unsupported_protect_level
Requested protection level is not supported.
DESCRIPTION
The rpc_binding_set_auth_info() routine sets up the specified server
binding handle so that it can be used to make authenticated remote
procedure calls that include authorization information.
Unless a client calls rpc_binding_set_auth_info() with the parameters
to set establish authentication and authorization methods, all remote
procedure calls made on the binding binding handle are unauthenti-
cated.Some authentication services (authn_svc) may need to
communicate with the Security service to perform this operation.
Otherwise, they may receive the rpc_s_comm_failure status.
The authn_svc parameter specifies the authentication service to use.
Since currently, there is only one available authentication service
(DCE shared-secret key), the parameter currently functions to specify
whether or not rpc calls will be authenticated and client PACs
certified. If authentication is chosen, the protect_level parameter
can specify a variety of protection levels, ranging from no
authentication to the highest level of authentication and encryption.
If the protect_level parameter is set to rpc_c_protect_level_none, no
authentication is performed, regardless of the authentication service
chosen.
The authz_svc parameter specifies the authorization service to use.
If no authentication has been chosen (authn_svc of rpc_c_authn_none),
then no authorization (authz_svc of rpc_c_authz_none) must be chosen
as well. If authentication will be performed, you have two choices
for authorization: name-based authorization and DCE authorization.
The use of name based_authorization, which provides a server with a
client's principal name, is not recommended. DCE authorization uses
PACs, a trusted mechanism for conveying client authorization data to
authenticated servers. PACs are designed to be used with the DCE ACL
facility.
Whether the call actually wakes up in the server manager code or is
rejected by the runtime depends on following conditions:
+ If the client specified no authentication, then none is attempted
by the RPC runtime.The call wakes up in the manager code whether
the server specified authentication or not. This permits both
authenticated and unauthenticated clients to call authenticated
servers. When the manager receives an unauthenticated call, it
needs to make a decision about how to proceed.
+ If the client specified DCE secret key authentication and the
server specified no authentication, then the runtime will fail
the call, and it will never reach the manager routine.
+ If both client and server specified DCE secret key
authentication, then authentication will be carried out
by the RPC runtime transparently. Whether the call reaches
the server manager code or is rejected by the runtime
depends on whether the authentication succeeded.
Although the RPC runtime is responsible any authentication that is
carried out, the fact that the runtime will always permit
unauthenticated clients to reach the manager code means that a
manager access function typically does need to make an
authentication check. When the manager access routine calls
rpc_binding_inq_auth_client() it needs to check for a status of
rpc_s_binding_has_no_auth. In this case, the client has specified
no authentication and the manager access function needs to make an
access decision based on this fact. Note that in such a case, no
meaningful authentication or authorization information is returned
from rpc_binding_inq_auth_client().
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_inq_auth_client
rpc_binding_inq_auth_info
rpc_mgmt_inq_dflt_protect_level
rpc_mgmt_inq_server_princ_name
sec_login_get_current_context
sec_login_newgroups
sec_login_setup_identity