Secure Communication Module User’s Guide : PART II Secure Sockets Package : Chapter 5 Advanced Topics : Using the Secure Sockets Callbacks
Using the Secure Sockets Callbacks
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.
NOTE >> 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.
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.
Parameter
Definition
char *buffer
The buffer into which the null terminated password string must be copied.
int bufLen
The maximum length of buffer. The length of the password plus the null terminator must be less than or equal to this number.
int flag
The flag parameter can be safely ignored, but it must be specified in the signature of the callback.The password callback is also called by the cryptographic library when the cryptographic library tries to write a key. In this case, the flag parameter is 1. The Secure Sockets package does not support writing keys, so this parameter is not needed.
The password callback function must return the length of the password.
If the password copied into buffer is incorrect, the exception RWUnableToReadPrivateKeyError is thrown.
For more information, see the example in examples\secsock\manual\InlineEncryptedKeyServer.cpp.
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.
Parameter
Definition
int ok
Contains 0 if the certificate failed or 1 if the certificate passed the internal verification procedure.
X509_STORE_CTX* store
References or points to the certificate data. You can use store to determine if you want to accept a certificate that the internal verification procedure rejected. For more information, see the manual that comes with your OpenSSL libraries.
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.
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.
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.