rpc_gss_set_svc_name Subroutine

Purpose

Sets the principal name that a server or a service represents.

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpcsec_gss.h>

bool_t rpc_gss_set_svc_name(s_principal, mech, r_time, prog, vers)
char *s_principal;
char *mech;
u_int r_time;
u_int prog;
u_int vers;

Description

When a client wants to use any service provided by a server with RPCSEC_GSS APIs, the client basically addresses server principals rather than actual services. A principal is a user or a service that uses authentication services and is identified in authentication database. The rpc_gss_set_svc_name subroutine sets the principal name that the server or service represents. You can use this subroutine to set more than one principal name to the same server or service.

Parameters

Item	Description
s_principal	Specifies a server principal of the form service@host. The service variable represents the service offered by a server and the host variable indicates the name of a machine on which the server resides (for example, `nfs@aix1.ibm.com`).
mech	Represents the supported security mechanism that is used for client-server communication (for example, `kerberosv5`).
r_time	Represents the time, in seconds, for which credentials must be valid. (The time is mechanism-dependent.)
prog	Represents the remote procedure call (RPC) program number of a service.
vers	Represents the RPC version number of a service.

Return Values

Item	Description
TRUE	successful
FALSE	unsuccessful

You can use the rpc_gss_get_error subroutine to retrieve the error number.

Examples

In the following example, the principal name is set for the RPC service with the program and version number that are provided by the server.

#include <stdlib.h>
#include <rpc/rpc.h>
#include <rpc/rpcsec_gss.h>

#define PROG 0x3fffffffL
#define VERS 0x1L
 
static void sample_dispatch(struct svc_req *, SVCXPRT *);
main()
{
    char *s_principal, *mech;
    u_int r_time
    rpc_gss_error_t gss_error;
   
    /* Create RPC service handle and register with RPCBIND service */

    /* Initialize the required parameters */ 
    s_principal = "myservice@aix1.ibm.com";   /* service@host */
    mech = "kerberosv5"; 
    r_time = 1000;
          
    /* Set the principal name */
    if(rpc_gss_set_svc_name(s_principal, mech, r_time, PROG, VERS) == FALSE)
    {
        fprintf(stderr,"\nError in rpc_gss_set_svc_name:\n");                    
        rpc_gss_get_error(&gss_error);
        fprintf(stderr,"rpc_gss_error: %d \nSystem_error: %d \n",
                gss_error.rpc_gss_error,gss_error.system_error);
        exit(EXIT_FAILURE);
     }
    svc_run();
    return 1;          
} 
      
/* following is the sample dispatch routine*/
static void sample_dispatch(struct svc_req *request, SVCXPRT *xprt)
{
    /* dispatch routine code */
}