Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Callbacks

Negotiation callbacks

Negotiation callbacks

Client-Library uses the negotiation callback to handle both trusted-user security handshakes and challenge/response security handshakes.

For more information on these types of handshakes, see the "Security features".

During server login, a challenge/response security handshake occurs when the server issues a challenge, to which the client must respond.

A connection uses a negotiation callback to provide its response to the challenge. To do this, the connection installs a negotiation callback routine. At connection time, when Client-Library receives the server challenge, Client-Library triggers the negotiation callback.

A connection that participates in challenge/response security handshakes must have its CS_SEC_CHALLENGE property or its CS_SEC_APPDEFINED property set to CS_TRUE.

When the application calls ct_connect to connect to the server:

1. If the server replies with a challenge, then Client-Library calls the connection's negotiation callback routine.

2. The negotiation callback routine generates the response and returns either CS_CONTINUE, CS_SUCCEED, or CS_FAIL.

   • If the callback routine returns CS_CONTINUE, Client-Library calls the negotiation callback again to get an additional response.

   • If the callback returns CS_SUCCEED, Client-Library sends the response(s) to the server.

   • If the callback returns CS_FAIL, Client-Library aborts the connection process, causing ct_connect to return CS_FAIL.

A negotiation callback is defined as follows:

CS_RETCODE CS_PUBLIC
 negotiation_cb(connection, inmsgid,
                 outmsgid, inbuffmt, inbuf, outbuffmt,
                 outbuf, outbufoutlen)
 
 CS_CONNECTION   *connection;
 CS_INT                      inmsgid;
 CS_INT                      *outmsgid;
 CS_DATAFMT            *inbuffmt;
 CS_BYTE                   *inbuf;
 CS_DATAFMT            *outbuffmt;
 CS_BYTE                   *outbuf;
 CS_INT                      *outbufoutlen;

where:

• connection is a pointer to the CS_CONNECTION structure representing the connection that is logging into the server.

• inmsgid is the type of information that the server is requesting. inmsgid can be any of the following values:

  Value of inmsgid	Meaning
  CS_MSG_GETLABELS	The server is requesting security labels.
  A value < CS_USER_MSGID	The server is requesting a Sybase-defined value.
  A user-defined value >= CS_USER_MSGID and <= CS_USER_MAX_MSGID	The Open Server application is requesting an application-defined value. The negotiation callback's must interpret inmsgid.

• outmsgid is the type of information that the negotiation callback is returning. This table lists the values that are legal for outmsgid:

  Value of outmsgid:	To indicate:
  CS_MSG_LABELS	The negotiation callback is returning security labels.
  A value < CS_USER_MSGID	The callback is returning a Sybase-defined value.
  A user-defined value >= CS_USER_MSGID and <= CS_USER_MAX_MSGID	The callback is returning an application-defined value.

• inbuffmt is a pointer to a CS_DATAFMT structure. If the negotiation callback is handling a trusted-user handshake, inbuffmt is NULL. If the negotiation callback is handling a challenge/response handshake, *inbuffmt describes the inbuf challenge key.

• inbuf is a pointer to data space. If the negotiation callback is handling a trusted-user handshake, inbuf is NULL. If the negotiation callback is handling a challenge/response handshake, inbuf points to the challenge key.

• outbuffmt is a pointer to a CS_DATAFMT structure. The negotiation callback should fill this CS_DATAFMT with a description of the security label or response that it is returning.

  Client-Library does not define which fields in the CS_DATAFMT need to be set.

• outbuf is a pointer to a buffer. The negotiation callback should place the security label or response in this buffer. This buffer is allocated and freed by Client-Library. Its length is described by outbuffmt−>maxlength.

• outbufoutlen is the length, in bytes, of the data placed in *outbuf.

A negotiation callback must return CS_SUCCEED, CS_FAIL, or CS_CONTINUE:

• If the callback returns CS_CONTINUE, Client-Library calls the negotiation callback again to generate an additional security label or response.

• If the callback returns CS_SUCCEED, Client-Library sends the security label(s) or response(s) to the server.

• If the callback returns CS_FAIL, Client-Library aborts the connection process, causing ct_connect to return CS_FAIL.