rpc_binding_set_auth_info(3rpc)
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. |
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. |
| Note: 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). |
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( )
These routines are described in DCE Security Service.
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. |
status
Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not.
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 handle are unauthenticated. 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_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.
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_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.
Related Information
Functions: rpc_binding_inq_auth_client(3rpc)
rpc_binding_inq_auth_info(3rpc)
rpc_mgmt_inq_dflt_protect_level(3rpc)
rpc_mgmt_inq_server_princ_name(3rpc)
sec_login_get_current_context(3sec)
sec_login_setup_identity(3sec)