NAME

catdasp_setprotocols - install DASP protocol handlers

SYNOPSIS

#include <cat/dasp.h>

int catdasp_setprotocols(catdasp_info *info, const catdasp_protocol *protolist, int nprotos);

DESCRIPTION

This function installs a number of protocol handlers in the info DASP structure.

protolist is a list of protocol handlers and nprotos is the number of handlers in the list.

Protocols will be negotiated in the order in which they are given. The list cannot mix server side handlers with client side handlers.

Each entry in the array of protocols is a structure that looks as follows:

  struct catdasp_protocol {
      char name[32];
      catdasp_protohandler *handler;
      void                 *data;
      catdb_func *db_func;
      void       *db_handle;
      int  ciphermask;              
      int rfd;
      int wfd;
      int  flags;
  };

where handler must match the following prototype:

  typedef int catdasp_protohandler(cat_session *session,
                                   catdasp_protocol *protodata,
                                   cat_data datafields[32],
                                   int     *nfields,
                                   int      callreason);

name is the protocol name as used during the DASP handshake.

handler is a function that implements the protocol.

data is any arbitrary data to be used by the handler.

The db_func can be called within the handler (with db_handle as argument) as a key cache function.

ciphermask is used by the handler to choose among ciphers and is set by the DASP handshake engine.

rfd and wfd are file descriptors associated with the session.

Bits that can be set in the flags field are:

CATDASP_SERVER_SIDE
Handles the server side of a protocol.

CATDASP_CLIENT_SIDE
Handles the client side of a protocol.

CATDASP_ASTART_DATA
Protocol supports ASTART data.

Either of the first two flags (server side or client side) must be set.

When the handler is called with the parameter datafields and nfields, valid datafields contains an nfields array of pairs of data pointer and data length.

A call to the handler is performed with callreason set to one of the following:

CATDASP_PROTO_ALLOC
When added in catdasp_setprotocols

Valid parameters - protodata

Return values - Ignored

Parameters session, datafields, and nfields are zero pointers.

CATDASP_PROTO_FREE
When removed in catdasp_setprotocols or catdasp_free_info

Valid parameters - protodata

Return values - Ignored

Parameters session, datafields, and nfields are zero pointers.

CATDASP_PROTO_INIT
When chosen in a DASP negotiation

Valid parameters - session and protodata

Return values - Ignored

Parameters datafields and nfields are zero pointers.

CATDASP_PROTO_DONE
The call is executed when catdasp_handshake intends to return CAT_OK and the state of the DASP negotiation is complete (read this is for pushing cryptographic filters).

Valid parameters - session and protodata

Return values - Ignored

Parameters datafields and nfields are zero pointers.

CATDASP_PROTO_ASTART
Called when DATA received and/or DATA required in ASTART packet.

Valid parameters - All.

Return values:

0 - Continue DASP handshake.

1 - Done. Protocol handler is ready.

Negative - Error code as described in cat.h

Other positive - Ignored

CATDASP_PROTO_PSTART
Called when PSTART received at the client side.

Valid parameters - All.

Return values:

0 - Continue DASP handshake (expect data from the network).

1 - Done. Protocol handler is ready.

2 - Again. Protocol handler wants to send more data.

Negative - Error code as described in cat.h

Other positive - Ignored

CATDASP_PROTO_DATA
Called when DATA received and/or DATA required .

Valid parameters - All.

Return values - See CATDASP_PROTO_PSTART.

CATDASP_PROTO_AGAIN
Called after handling the last return (which probably sent data) when the last call returned Again.

Valid parameters - All.

Return values - See CATDASP_PROTO_PSTART.

RETURN VALUES

The function returns 0 if successful, or a negative code on error.

SEE ALSO

cat, catdasp