rpc_gss_seccreate Subroutine

Purpose

Creates a security context.

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpcsec_gss.h>

AUTH *rpc_gss_seccreate(cl, s_principal, mech, s_type, qop, o_req, o_ret)
CLIENT *cl;
char *s_principal;
char *mech;
rpc_gss_service_t s_type;
char *qop;
rpc_gss_options_req_t *o_req;
rpc_gss_options_ret_t *o_ret;

Description

When making a remote procedure call using RPCSEC_GSS APIs, a security context must be created between the client and the server. The rpc_gss_seccreate subroutine uses the RPCSEC_GSS protocol to create a context. With the subroutine, you can specify the security mechanism that is used for context creation and thus for further client-server communication, security types and the quality of protection.

Parameters

Item	Description
cl	Represents a client handle that can be created using any of the client handle creation subroutines.
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 context creation and client-server communication (for example, `kerberosv5`).
s_type	Represents the type of service for the session that basically offers a level of protection. (for example, integrity and privacy).
qop	Represents the quality of protection. You can specify the parameter to select cryptographic algorithm.
o_req	Specifies the options that are passed to the GSS_API layer under the RPCSEC_GSS layer. If you specify the parameter with NULL, default parameters are used.
o_ret	Specifies the options that are returned by the GSS_API layer. If you do not want to see options, you can specify the parameter with NULL. The o_ret parameter is an output parameter.

Return Values

Item	Description
a security context handle of the AUTH type	successful
NULL	unsuccessful

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

Examples

In the following example, security context is created to have a secure communication between the client and the server.

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

main()
{
    CLIENT *client;
    char *s_principal;
    char *mech;
    rpc_gss_service_t s_type;
    char *qop;          
    rpc_gss_options_ret_t o_ret; 
    rpc_gss_error_t gss_error;

    /* Create client handle using any of the client handle creation routines*/
   
    /* Initialize the required parameters */ 
    s_principal = "myservice@aix1.ibm.com";   /* service@host */
    mech = "kerberosv5"; 
    s_type = 2;             /* 1: none, 2: integrity. 3: privacy */
    qop = "GSS_C_QOP_DEFAULT";
    o_ret.major_status = 0;
    o_ret.minor_status = 0;
   
    /* Create security context */
    client->cl_auth = rpc_gss_seccreate(client, s_principal, 
                           mech, s_type, qop, NULL, &0_ret);
    if(client->cl_auth == NULL)
    {
         fprintf(stderr,"\nError in rpc_gss_seccreate:\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);
     }
    /* Make a call to server */
}