NAME

catssl_clienthandshake - client side SSL negotiation

SYNOPSIS

#include <cat/cat.h>

int catssl_clienthandshake(cat_session *sess, catssl_info *info, int fd_ids);

DESCRIPTION

This function performs the client side of an SSL negotiation on the descriptors specified by fd_ids. One read descriptor and one write descriptor must be given. Specifying fd_ids as 0 uses causes the default, (CAT_SERVER_RFD | CAT_SERVER_WFD), to be used.

This function normally blocks during the SSL handshake, and will not return until it is completed or has failed.

If the session is non-blocking, catssl_serverhandshake will return CAT_EAGAIN when it is unable to proceed without more input from the peer. The function should be called again when data is available. Calls to the function should be repeated until the SSL negotiation succeeds or an error other than CAT_EAGAIN is returned.

A successful negotiation causes an encryption filter to be pushed. The SSL context becomes the property of the session, and should be neither reused nor freed.

Note that the local certificate and associated private RSA key must be made available before calling this function. This can be achieved by calling catpsd_setpsd().

RETURN VALUES

The function returns zero if successful, in which case the server side certificate can be retrieved with the catcert_getpeercert() function; a negative code is returned on error.

If operating on a non-blocking session, CAT_EAGAIN will be returned when the function runs out of data.

SEE ALSO

cat, catssl

catpsd_setpsd, catssl_setdb