Using the Security 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 HTTPS package includes a security callback mechanism that requests the certificate of the server and compares the name in the certificate to the name of the host. This function is important because an attacker could divert your HTTPS request to another server and supply you with a valid certificate for that server instead.

This is how the callback mechanism works:

1. After a connection is established, the HTTPS package calls a certificate name check callback. The default version of this callback compares the “Common Name” field in the certificate to the host name. For more information, see “Certificate Name Check Callback.”

2. If the certificate name check callback returns false, the name in the certificate is not the same as the name of the host, and the certificate name mismatch callback is called. The default version of this callback throws an exception of type RWHttpsCertificateNameMismatch. For more information, see “Certificate Name Mismatch Callback.”

The default versions of these callbacks are sufficient for many applications. They are implemented using functors from the Functor package of the Threads Module of SourcePro Core. Functors are more flexible than pointers to functions because they allow you to pass extra arguments to the function as callee data. Also, you do not need to cast those arguments to a void* pointer, as most pointer-to-function implementations use. See the Threads Module User’s Guide for more information on functors.

If you want to write your own callbacks, see “Supplying Your Own Callbacks.”

For more information about security, see SSL and TLS - Designing and Building Secure Systems, by Eric Rescorla, referenced in Appendix B.

Checking the certificate name is performed by a function called the certificate name check callback. The HTTPS package provides a default version of this function that compares the “Common Name” field in the certificate to the name of the host to which your application is actually connected. This default version supports the use of the * wildcard in host names. See RFC 2818 for more information.

NOTE >> The HTTPS RFC states that this method of name verification is deprecated, but it is widely used on the Internet today. The HTTPS RFC recommends checking the dNSName extension of the certificate, but because few certificates have the dNSName extension, code to check it is not included.

You can change the default certificate name check callback to any function that you supply. See “Supplying Your Own Callbacks.” for information on how to write a certificate name check callback.

When the certificate name check callback fails, the HTTPS package calls the certificate name mismatch callback. The default certificate name mismatch callback throws an exception of type RWHttpsCertificateNameMismatch. In most cases, this is unacceptable because it stops the connection.

You should almost always define your own certificate name mismatch callback. For some applications, terminating the program may be appropriate; for others, it might be better to display a dialog box that allows the user to ignore the situation. For information about defining a callback, see “Supplying Your Own Callbacks.”