srv_negotiate

Description

Send to and receive from a client, negotiated login information.

Syntax

CS_RETCODE srv_negotiate(spp, cmd, type)

SRV_PROC    *spp;
CS_INT           cmd;
CS_INT          type;

Parameters

spp: A pointer to an internal thread control structure.

cmd

Indicates whether the application is calling srv_negotiate to send or retrieve negotiated login information. The following table describes the legal values for cmd:

**Table 3-66: Values for cmd (srv_negotiate)**
Value	Description
CS_SET	The negotiated login information defined by type is to be sent to the client.
CS_GET	The negotiated login information defined by type is to be read from the client.

type

The type of negotiated login information to be sent to or read from a client. The following table describes the legal values for type:

**Table 3-67: Values for type (srv_negotiate)**
Value	Description
SRV_NEG_CHALLENGE	The negotiated login information is a challenge byte stream sent to the client (CS_SET) or a challenge response byte stream read from the client (CS_GET).
SRV_NEG_ENCRYPT	The negotiated login information consists of an encryption key sent to the client. The client will then use this to encrypt its local and remote passwords. This type is only valid when cmd is CS_SET.
SRV_NEG_LOCPWD	The encrypted local password sent by the client in response to a SRV_NEG_ENCRYPT challenge. This type is only valid when cmd is CS_GET.
SRV_NEG_REMPWD	The negotiated login information is a variable number of remote server name and encrypted remote password pairs sent by the client in response to a SRV_NEG_ENCRYPT challenge. This type is only valid when cmd is CS_GET.
SRV_NEG_SECLABEL	The negotiated login information is a request for security labels sent to the client, or a set of security labels sent by the client to the server.
SRV_NEG_SECSESSION	The negotiated login information is used by a full passthrough gateway application to establish a direct security session between a gateway client and a remote server. This is similar to challenge-response security negotiation. Refer to “Security services” for more information and for an example security session callback.
An integer value between CS_USER_MSGID and CS_USER_MAX_MSGID, inclusive.	The negotiated login information is part of an application-defined handshake, identified by the type argument itself.

Returns

**Table 3-68: Return values (srv_negotiate)**
Returns	To indicate
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.

Examples

Example 1

#include  <ospublic.h>

/*

** Local Prototype.

*/

CS_RETCODE    ex_srv_negotiate PROTOTYPE((

SRV_PROC      *sproc

));

/*

** EX_SRV_NEGOTIATE

**  An example routine to retrieve negotiated login information

 **  by using srv_negotiate.

**

** Arguments:

**  sproc  A pointer to an internal thread control structure.

**

** Returns:

**  CS_SUCCEED   The login information was retrieved.

**  CS_FAIL      An error was detected.

*/

CS_RETCODE   ex_srv_negotiate(sproc)

SRV_PROC     *sproc;

/*

    ** Check to make sure that the thread control structure is

     ** not NULL.

*/

    if ( sproc == (SRV_PROC *)NULL )

        return(CS_FAIL);

    /* Now get the login information. */

    if ( srv_negotiate(sproc, CS_GET, SRV_NEG_CHALLENGE) ==          CS_FAIL )

        return(CS_FAIL);

    return(CS_SUCCEED);

Usage

srv_negotiate is used to send negotiated login information to, and receive negotiated login responses from, a client.
through srv_negotiate, Open Server applications can implement a secure login process inside their SRV_CONNECT event handler. In a secure computing environment, an application may want to perform more rigorous authentication at connect time to verify that clients are who they claim to be, by issuing negotiated login challenges and encrypted passwords.
An Open Server application can choose to send a challenge or encrypted password to the client while in the SRV_CONNECT event handler, to authenticate the login attempt.
Once an application has sent a negotiated login challenge or encrypted password, it must read the client’s response before the connection process can continue.
An Open Server application can go through as many challenge or response iterations as are necessary to authenticate the login attempt. However, the application must read in the response to each challenge before sending another challenge.
Once a negotiated login challenge has been sent to a client, the application must read the response before the connection process can continue.
An Open Server application must punctuate any type of challenge with a call to srv_senddone. If the application issues a batch of several challenges before it reads a response, it must call srv_senddone with a status argument of SRV_DONE_MORE after each challenge but the last one in the batch. After the last challenge in the batch, the application must call srv_senddone with a status argument of SRV_DONE_FINAL.
For application-defined handshakes, an Open Server application can set the type argument to a value between CS_USER_MSGID and CS_USER_MAX_MSGID to set the handshake type (CS_SET) or specify the type of reply the client should be sending in response (CS_GET). If the Open Server application receives an unexpected value, Open Server raises an error.
When a client responds to a challenge or encrypted password, srv_negotiate suspends the thread’s execution until the client’s response has arrived. Applications should bear this in mind when coding a secure SRV_CONNECT event handler.
Negotiated login challenges and responses carry data values through parameters, which are sent and received through srv_bind, srv_desc&fmt, and srv_xferdata.These three routines take a type argument of SRV_NEGDATA to define or access negotiated login data.

The following table lists the parameter or parameters that accompany each type of challenge sent to a client:

**Table 3-69: Required challenge parameters (srv_negotiate)**
Negotiated login type	Parameters required
SRV_NEG_CHALLENGE	One parameter – Challenge-data value. Datatype is CS_BINARY_TYPE with the CS_DATA&fmt status field set to CS_CANBENULL.
SRV_NEG_ENCRYPT	One parameter – Encryption key data value. Datatype is CS_BINARY_TYPE with the CS_DATA&fmt status field set to CS_CANBENULL.
SRV_NEG_SECLABEL	No parameters.
SRV_NEG_SECSESSION	The security session callback specifies the number of parameters and their data formats. Refer to “Security session callbacks” and to the Open Client Client-Library/C Reference Manual.
An integer value between CS_USER_MSGID and CS_USER_MAX_MSGID, inclusive.	One parameter – Application-defined login handshake data value.

The following table lists the parameter that should be read from a client for each type of negotiated login challenge:

**Table 3-70: Expected challenge parameters (srv_negotiate)**
Negotiated login type	Parameters present
SRV_NEG_CHALLENGE	One parameter – Challenge response data.
SRV_NEG_LOCPWD	One parameter – Encrypted local password.
SRV_NEG_REMPWD	A variable number of server-name/password pairs.
SRV_NEG_SECLABEL	Four parameters: Param 1: Maximum read level label. Param 2: Maximum write level label. Param 3: Minimum write level label. Param 4: Current write level label.
SRV_NEG_SECSESSION	The security session callback specifies the number of parameters and their data formats. Refer to “Security session callbacks” and to the Open Client Client-Library/C Reference Manual.
An integer value between CS_USER_MSGID and CS_USER_MAX_MSGID, inclusive.	One parameter – Application-defined login handshake data value.

Note that a response to a password encryption challenge, SRV_NEG_ENCRYPT, can consist of two sets of parameters. The SRV_NEG_LOCPWD response carries a parameter indicating the client’s encrypted password. The client can also send a SRV_NEG_REMPWD response, which carries parameters indicating the client’s encrypted remote server password and the remote server name, respectively. The SRV_NEG_LOCPWD response to a SRV_NEG_ENCRYPT challenge will always be present. If no remote server passwords were sent by the client, a request to receive a SRV_NEG_REMPWD response will fail.
Applications that use Open Client and Open Server to implement gateway functionality must use Open Client’s negotiated login callback mechanism to route negotiated login challenges and responses between clients and the remote server. In this type of application, the Open Client negotiated login callback must contain the Server-Library routine calls necessary to forward a challenge to the client, and receive the response, which Open Client then returns to the remote server.

If the gateway application intends to establish a direct security session between clients and a remote server, then an Open Client security session callback is required. This callback must contain the Server-Library calls necessary to forward the opaque security tokens to the client, and receive the response, which the Open Client then returns to the remote server. Refer to “Security session callbacks” and to the Open Client Client-Library/C Reference Manual, for more information.