doc: correct the SSL_CTX_set_info_callback(3) manual page

[mspncp]

The info callback is not prototyped correctly, and the code example fails to compile because of const-incorrectness.

[mspncp]

Testcase

The implementation of apps_ssl_info_callback in the following test program was copied literally from the manual page. It fails with the following error, which can be fixed by constifying the first argument of apps_ssl_info_callback from SSL *s to const SSL *s.

make -k
cc -g -O0 -I/opt/openssl-dev/master/include -Wno-deprecated-declarations  -L/opt/openssl-dev/master/lib -Wl,--enable-new-dtags,-rpath,/opt/openssl-dev/master/lib  demo.c  -lcrypto -lssl -o demo
demo.c: In function 'main':
demo.c:40:37: warning: passing argument 2 of 'SSL_CTX_set_info_callback' from incompatible pointer type [-Wincompatible-pointer-types]
   40 |     SSL_CTX_set_info_callback(NULL, apps_ssl_info_callback);
      |                                     ^~~~~~~~~~~~~~~~~~~~~~
      |                                     |
      |                                     void (*)(SSL *, int,  int) {aka void (*)(struct ssl_st *, int,  int)}
In file included from demo.c:2:
/opt/openssl-dev/master/include/openssl/ssl.h:764:39: note: expected 'void (*)(const SSL *, int,  int)' {aka 'void (*)(const struct ssl_st *, int,  int)'} but argument is of type 'void (*)(SSL *, int,  int)' {aka 'void (*)(struct ssl_st *, int,  int)'}
  764 |                                void (*cb) (const SSL *ssl, int type, int val));
      |                                ~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
demo.c:41:33: warning: passing argument 2 of 'SSL_set_info_callback' from incompatible pointer type [-Wincompatible-pointer-types]
   41 |     SSL_set_info_callback(NULL, apps_ssl_info_callback);
      |                                 ^~~~~~~~~~~~~~~~~~~~~~
      |                                 |
      |                                 void (*)(SSL *, int,  int) {aka void (*)(struct ssl_st *, int,  int)}
/opt/openssl-dev/master/include/openssl/ssl.h:2183:35: note: expected 'void (*)(const SSL *, int,  int)' {aka 'void (*)(const struct ssl_st *, int,  int)'} but argument is of type 'void (*)(SSL *, int,  int)' {aka 'void (*)(struct ssl_st *, int,  int)'}
 2183 |                            void (*cb) (const SSL *ssl, int type, int val));
      |                            ~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

demo.c

#include <openssl/bio.h>
#include <openssl/ssl.h>

BIO * bio_err = NULL;

void apps_ssl_info_callback(SSL *s, int where, int ret)
{
    const char *str;
    int w = where & ~SSL_ST_MASK;

    if (w & SSL_ST_CONNECT)
        str = "SSL_connect";
    else if (w & SSL_ST_ACCEPT)
        str = "SSL_accept";
    else
        str = "undefined";

    if (where & SSL_CB_LOOP) {
        BIO_printf(bio_err, "%s:%s\n", str, SSL_state_string_long(s));
    } else if (where & SSL_CB_ALERT) {
        str = (where & SSL_CB_READ) ? "read" : "write";
        BIO_printf(bio_err, "SSL3 alert %s:%s:%s\n", str,
                   SSL_alert_type_string_long(ret),
                   SSL_alert_desc_string_long(ret));
    } else if (where & SSL_CB_EXIT) {
        if (ret == 0) {
            BIO_printf(bio_err, "%s:failed in %s\n",
                       str, SSL_state_string_long(s));
        } else if (ret < 0) {
            BIO_printf(bio_err, "%s:error in %s\n",
                       str, SSL_state_string_long(s));
        }
    }
}



int main (int argc, char *argv[])
{
    SSL_CTX_set_info_callback(NULL, apps_ssl_info_callback);
    SSL_set_info_callback(NULL, apps_ssl_info_callback);

    return 0;
}

Makefile

OPENSSL_VERSION=master
OPENSSL_PREFIX=/opt/openssl-dev/${OPENSSL_VERSION}


OPENSSL_INCDIR=${OPENSSL_PREFIX}/include
OPENSSL_LIBDIR=${OPENSSL_PREFIX}/lib

CFLAGS=-g -O0 -I${OPENSSL_INCDIR} -Wno-deprecated-declarations
LDFLAGS=-L${OPENSSL_LIBDIR} -Wl,--enable-new-dtags,-rpath,${OPENSSL_LIBDIR}
LDLIBS=-lcrypto -lssl

all: demo

clean:
	rm -f demo *~ \#*#

[mspncp]

@t8m I forgot to check the getters, they needed to be fixed as well. Please reapprove.

[mspncp]

For your convenience:

openssl/include/openssl/ssl.h.in

Lines 740 to 743 in 8ed76c6

	void SSL_CTX_set_info_callback(SSL_CTX *ctx,
	void (*cb) (const SSL *ssl, int type, int val));
	void (*SSL_CTX_get_info_callback(SSL_CTX *ctx)) (const SSL *ssl, int type,
	int val);

openssl/include/openssl/ssl.h.in

Lines 2110 to 2113 in 8ed76c6

	void SSL_set_info_callback(SSL *ssl,
	void (*cb) (const SSL *ssl, int type, int val));
	void (*SSL_get_info_callback(const SSL *ssl)) (const SSL *ssl, int type,
	int val);

[openssl-machine]

This pull request is ready to merge

[t8m]

Merged to master, 3.1, and 3.0 branches. Thank you.