A callback is a function that is executed when a certain condition is met. Usually, each callback is registered with a specific class. The following section describe:

• password callbacks

• certificate verification callbacks

• handshake information callbacks

• client certificate callbacks

These callbacks depend on features of the underlying cryptographic library. Note that all user callback functions for the Secure Sockets package should have "C" linkage by using extern "C" in your function declarations.

---

Rogue Wave does not provide technical support for writing these callbacks. The functions in the Secure Sockets package that set the callback are provided for convenience only. For more information, see the manual that came with your cryptographic library.

---

5.5.1 Password Callback

The password callback is invoked when an attempt is made to construct a key from encrypted data. The password callback supplies the password with which the key was encrypted. The signature of the callback function is:

extern "C" int passwordCallback(char *buffer, int bufLen, int flag);

The following table describes the parameters and their definitions.

The password callback function must return the length of the password.

5.5.2 Certificate Verification Callback

The certificate verification callback is invoked for every certificate in the certificate chain that is passed to the client during the handshake. This callback is set with either RWSecureSocketContext::setCertificateVerifyCallback() or RWSecureSocketContext::setVerify(). The signature of the callback function is:

extern "C" int verify_callback(int ok, X509_STORE_CTX* store);

The following table describes the parameters and their definitions.

The callback should return 0 if the certificate failed or 1 if the certificate passed your verification procedure, after taking into account what the internal verification procedure returned. Normally the ok parameter is returned, because the internal verification procedure is usually sufficient.

For more information, see the description of the function SSL_CTX_set_verify() in the OpenSSL reference guide.

5.5.3 Handshake Information Callback

The handshake information callback is invoked during an SSL/TLS handshake. This callback is useful when debugging applications. It is set with the RWSecureSocket::setInfoCallback() function. The signature of the callback function is:

extern "C" void info_callback(SSL* ssl, int where, int ret);

The ssl parameter is the ssl connection instance. The where parameter indicates where the callback was called from. The ret parameter is not used.

Normally, the callback is written so that it switches on the where parameter. Each case statement would output a string that indicates the meaning of the where parameter.

For more information, see the description of SSL_set_info_cb() and ssl_info_cb() in the OpenSSL reference manual.

5.5.4 Client Certificate Callback

The client certificate callback is invoked when a server requests a client certificate. It is useful when a client must choose which certificate to send back to the server. The certificate and private key to be sent are returned through the callback argument list. The callback is set with:

RWSecureSocketContext::setClientCertificateCallback();

The signature of the callback function is:

extern "C" int client_cert_cb(SSL* ssl, X509** cert, EVP_PKEY** pkey);

The ssl parameter is the ssl connection. The cert and pkey parameters are used to return certificate and private key pointers to the server.

This function should return 1 to send the certificate and private key to the server. Otherwise it should return 0.

For more information, see the description of SSL_CTX_set_client_cert_cb() in the OpenSSL reference manual.