Send to and receive from a client, negotiated login information.
CS_RETCODE srv_negotiate(spp, cmd, type)
SRV_PROC *spp; CS_INT cmd; CS_INT type;
A pointer to an internal thread control structure.
Indicates whether the application is calling srv_negotiate to send or retrieve negotiated login information. Table 3-67 describes the legal values for cmd:
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. |
The type of negotiated login information to be sent to or read from a client. Table 3-68 describes the legal values for type:
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_EXTENDED_ENCRYPT |
The negotiated login information and public key used to encrypt the password.These information are used by the client. This type is only valid when cmd is CS_SET. |
SRV_NEG_EXTENDED_LOCPWD |
The public key encrypted password sent by the client in response to a SRV_NEG_EXTENDED_ENCRYPT challenge. This type is only valid when cmd is CS_GET. |
SRV_NEG_EXTENDED_REMPWD |
The negotiated login information is a variable number of pairs of remote server names and corresponding public key encrypted password sent by the client in response to a SRV_NEG_EXTENDED_ENCRYPT challenge. This type is only valid when cmd is CS_GET. |
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 |
To indicate |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
#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);
}
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_descfmt, and srv_xferdata.These three routines take a type argument of SRV_NEGDATA to define or access negotiated login data.
Table 3-70 lists the parameter or parameters that accompany each type of challenge sent to a client:
Negotiated login type |
Parameters required |
|---|---|
SRV_NEG_CHALLENGE |
One parameter – Challenge-data value. Datatype is CS_BINARY_TYPE with the CS_DATAFMT status field set to CS_CANBENULL. |
SRV_NEG_ENCRYPT |
One parameter – Encryption key data value. Datatype is CS_BINARY_TYPE with the CS_DATAFMT 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. |
Table 3-71 lists the parameter that should be read from a client for each type of negotiated login challenge:
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.
