dbsechandle

Description

Install user functions to handle secure logins.

Syntax

RETCODE *dbsechandle(type, handler)
 
DBINT                type;
INTFUNCPTR     (*handler)();

Parameters

type

An integer variable with one of the symbolic values shown in Table 2-25.

**Table 2-25: Values for type (dbsechandle)**
Value of type	dbsechandle
DBENCRYPT	Installs a function to handle password encryption
DBLABELS	Installs a function to handle login security labels

handler: A pointer to the user function that DB-Library will call whenever the corresponding type of secure login needs to be handled.

If handler is NULL and type is DBENCRYPT, DB-Library will use its default encryption handler.

If handler is NULL and type is DBLABELS, dbsechandle uninstalls any current label handler.

Returns

SUCCEED or FAIL.

Usage

dbsechandle installs user functions to handle secure logins.
An application can use dbsechandle to install functions to handle two types of secure logins:
- Encrypted password secure logins
  
  In this type of secure login, the server provides the client with a key. The client uses the key to encrypt a password, which it then returns to the server.
- Security label secure logins
  
  In this type of secure login, the server asks the client for identifying security labels, which the client then provides.

Encrypted password secure logins

If type is DBENCRYPT, dbsechandle installs the function that DB-Library will call when encrypting user passwords.
DB-Library will perform password encryption only if DBSETLENCRYPT has been called prior to calling dbopen.
DB-Library will call its default encryption handler if a user function has not been installed.
Typically, a user function does not need to be installed for password encryption. This is because DB-Library’s default encryption handler allows an application to perform password encryption when connecting to an Adaptive Server Enterprise.
A user-defined encryption handler should be installed by applications that are gateways. The encryption handler will be responsible for taking the encryption key returned by the remote server, passing it back to the client, reading the encrypted password from the client, and returning the encrypted password to DB-Library so that DB-Library can pass it on to the remote server.
An encryption handler should be declared as shown in the example below. Encryption handlers on the Windows platform must be declared with CS_PUBLIC. For portability, callback handlers on other platforms should be declared CS_PUBLIC as well. Here is a sample declaration:
```
RETCODE CS_PUBLIC encryption_handler(dbproc, pwd, 
```
```
    pwdlen, enc_key, keylen, outbuf, buflen, outlen)
```
```
 DBPROCESS   *dbproc;
```
```
 BYTE        *pwd;
```
```
 DBINT       pwdlen;
```
```
 BYTE        *enc_key;
```
```
 DBINT       keylen;
```
```
 BYTE        *outbuf;
```
```
 DBINT       buflen;
```
```
 DBINT       *outlen;
```
where:
- dbproc is the DBPROCESS.
- pwd is the user password to be encrypted.
- pwdlen is the length of the user’s password.
- enc_key is the key to be used during encryption.
- keylen is the length of the encryption key.
- outbuf is a buffer in which the callback can place the encrypted password. This buffer will be allocated and freed by DB-Library.
- buflen is the length of the output buffer.
- outlen is a pointer to a DBINT. The encryption handler should set *outlen to the length of the encrypted password.
An encryption handler should return SUCCEED to indicate that the password was encrypted successfully. If the encryption handler returns a value other than SUCCEED, DB-Library will abort the connection attempt.

Security label secure logins

If type is DBLABELS, dbsechandle installs a function that DB-Library will call to get login security labels.

DB-Library will send login security labels only if DBSETLABELLED has been called prior to calling dbopen.

There are two ways for an application to define security labels:

The application can call dbsetsecurity one time for each label it wants to define. Most applications will use this method.
The application can call dbsechandle to install a user-supplied function to generate security labels. Typically, only gateway applications will use this method.

If an application uses both methods, the labels defined through dbsetsecurity and the labels generated by the user-supplied function are sent to the server at the same time.

DB-Library calls an application’s label handler during the connection process, in response to a server request for login security labels. Each time it is called, the label handler returns a single label. DB-Library sends these labels, together with any labels previously defined using dbsetsecurity, to the server.

DB-Library does not have a default label handler.

A user-defined label handler should be installed by applications that are gateways. The label handler will be responsible for reading the client’s login security labels and passing them on to DB-Library so that DB-Library can pass them on to the remote server.

A label handler should be declared as shown in the example below. Label handlers on the Windows platform must be declared with CS_PUBLIC. For portability, callback handlers on other platforms should be declared CS_PUBLIC as well. Here is a sample declaration:

RETCODE CS_PUBLIC label_handler(dbproc, namebuf,

nbuflen, valuebuf, vbuflen, namelen, valuelen)

 DBPROCESS   *dbproc;

 DBCHAR      *namebuf;

 DBINT       nbuflen;

 DBCHAR      *valuebuf;

 DBINT       vbuflen;

 DBINT       *namelen;

 DBINT       *valuelen;

where:

dbproc is the DBPROCESS.
namebuf is a buffer in which the handler can place the name of the login security label. This buffer is allocated and freed by DB-Library.
nbuflen is the length of the namebuf buffer.
valuebuf is a buffer in which the handler can place the value of the login security label. This buffer is allocated and freed by DB-Library.
vbuflen is the length of the valuebuf buffer.
namelen is a pointer to a DBINT. The label handler should set *namelen to the length of the label name placed in namebuf.
valuelen is a pointer to a DBINT. The label handler should set *valuelen to the length of the label value placed in valuebuf.

Table 2-26 lists the return values that are legal for a security label handler. A security label handler must return one of these values.

**Table 2-26: Return values for security label handlers**
Label handler return value	Indicates
DBMORELABEL	The label handler has set the name and value of a login security label. DB-Library should call the label handler again to get an additional label.
DBENDLABEL	The label handler has set the name and value of a login security label. DB-Library should not call the label handler again.
DBERRLABEL	A label handler error has occurred. DB-Library should abort the connection attempt.