Open Client Client-Library/C Reference Manual

Home

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Callbacks

Security session callbacks

An Open Server gateway needs a security session callback only if all of the following statements are true:

The Open Server is a gateway.
The gateway allows clients to connect using network-based user authentication.
The gateway wants to establish a direct security session between the gateway's client and the remote server.

If not all of the above conditions apply, Client-Library provides a default callback that is adequate.

See "Requesting login authentication services".

Establishing a direct security session

A security session is a client/server connection where the client and the server have agreed to use an external security mechanism (such as DCE) and a set of security services (such as data encryption).

In a gateway application, a direct security session is established between a gateway's client and a remote server. The gateway acts as an intermediary while the session is established, but afterwards, the gateway is not part of the security session. Direct security sessions are useful in the following circumstances:

Full-passthrough gateways that support per-packet security services
A full-passthrough gateway establishes a direct security session to support per-packet security services such as data integrity and data confidentiality while eliminating some of the associated overhead. For example, if the gateway supports data confidentiality without a direct security session, the contents of each TDS packet that passes through the gateway must be decrypted upon receipt and reencrypted upon sending. If the gateway does not inspect the packet contents, this overhead is unnecessary. With a direct security session, no per-packet services are performed within the gateway.
Gateways where delegated client credentials are not available
A gateway's clients may not delegate their security credentials to a gateway (using the CS_SEC_DELEGATION connection property), or a security mechanism may not support credential delegation. In these cases, the gateway must set up a direct security session to connect to the remote server using the same user name as the gateway's client.

A security session callback allows the gateway to set up a direct security session. When the connection to the remote server is made, the callback routine acts as an intermediary for the handshaking required between the remote server and the gateway's client. The handshaking process is outlined below:

When the gateway calls ct_connect, the remote server issues one or more security session messages.
For each security session message sent by the remote server, Client-Library invokes the callback, passing the security session information sent by the remote server as the callback's input parameters.
The callback forwards the information to the gateway's client by calling the Server-Library routine srv_negotiate(CS_SET, SRV_NEG_SECSESSION).
The callback then reads the client's response and returns it to Client-Library via the callback's output parameters.
Client-Library forwards the response to the remote server.

If the remote server sends another security session message, the process is repeated.

Defining a security session callback

A security session callback is defined as follows:

CS_RETCODE CS_PUBLIC 
 secsession_cb (conn, 
               numinputs, infmt, inbuf, 
               numoutputs, outfmt, outbuf, outlen)
 CS_CONNECTION    *conn;
 CS_INT                       numinputs;
 CS_DATAFMT            *infmt;
 CS_BYTE                   **inbuf;
 CS_INT                       *numoutputs;
 CS_DATAFMT             *outfmt;
 CS_BYTE                    **outbuf;
 CS_INT                        *outlen;

where:

connection is a pointer to the connection structure that controls the connection to the gateway's remote server.
numinputs is the number of input parameters sent by the remote server with the security session message.
infmt is the address of an array of CS_DATAFMT structures that describe each input parameter sent by the remote server.
inbuf is the address of an array of CS_BYTE * pointers that point to buffers containing the data for each input parameter. The length of each buffer inbuf[i] is given as infmt[i] ->.maxlength
numoutputs is the address of a CS_INT. The callback must return the number of items sent by the client in *numoutputs. On input, *numoutputs specifies the length of the outfmt, outbuf, and outlen arrays.
outfmt is the address of an array of CS_DATAFMT structures. The callback must place a description of each item in the client's response into the corresponding CS_DATAFMT structure. The input value of *numoutputs specifies the length of this array.
outbuf is the address of an array of CS_BYTE * buffers. The callback must copy the data items from the client's response into the corresponding buffer. The input value of *numoutputs specifies the length of this array, and for each buffer i, the input value of outfmt[i]−>maxlength specifies the allocated length of the buffer pointed at by outbuf[i].
outlen is the address of an array of CS_INT. The callback places the number of bytes written to each buffer into outlen[i].

The callback forwards the security session message data and reads the client's response with Server-Library calls. See the reference page for srv_negotiate in the Open Server Server-Library/C Reference Manual.

A security session callback returns CS_SUCCEED or CS_FAIL. If the callback returns CS_FAIL, Client-Library aborts the connection attempt. Other return values are illegal: Client-Library responds by raising an error and aborting the connection attempt.


	Expand Search