Topic: Bad documentation for wolfSSL_UseSNI

There is no documentation on the website that I can find (search returns "no matches").

However, there is documentation in the source tree (doc/dox_comments/header_files/ssl.h) for `wolfSSL_UseSNI` which states:

\return SSL_SUCCESS upon success

followed by example code:

ret = wolfSSL_UseSNI(ssl, WOLFSSL_SNI_HOST_NAME, "www.yassl.com", strlen("www.yassl.com"));
    if (ret != 0) {
        // sni usage failed
    }

Note that `SSL_SUCCESS` is a (deprecated?) old name, at most defined to be `WOLFSSL_SUCCESS` which is equal 1, not 0.

Looking at the actual code,

`wolfSSL_UseSNI` returns `TLSX_UseSNI` which returns, upon errors, the negative values BAD_FUNC_ARG or MEMORY_E but also contains the code:

        if (ret != 0) {                                  
            TLSX_SNI_Free(sni, heap);
            return ret;
        }
...
    return WOLFSSL_SUCCESS;

The last line matches the documentation (but not the example) but the first line feels error prone.
Looking more closely to the actual code and functions called, we can establish that this won't
return the value 1 (WOLFSSL_SUCCESS) after just having freed sni... But it doesn't look very
robust to me.

There seems to be a duality in the code on what the meaning of the return value '0' means.
Sometimes it means 'success' and sometimes it means WOLFSSL_FAILURE.

Proof that this is bad is the fact that the documentation contains examples that confuse the two.

Share

Re: Bad documentation for wolfSSL_UseSNI

Hi Carlo,

Thanks for pointing our the doxy return code error in the example. I've updated that.

The documentation you seek for SNI is in the wolfSSL user manual in chapter 4.
https://www.wolfssl.com/docs/wolfssl-manual/ch4/
See 4.9 SERVER NAME INDICATION

We do have a mix of zero return and WOLFSSL_SUCCESS/WOLFSSL_FAILURE. The wolfSSL_ level API's typically use the success/failure return codes and the reasoning goes back to the openssl compatibility layer which expects these. For our internal API's and wolfCrypt API's we prefer to use 0 to indicate success.

Thanks,
David Garske, wolfSSL

Share

Re: Bad documentation for wolfSSL_UseSNI

Hi Carlo,

For reference that SNI documentation PR is here https://github.com/wolfSSL/wolfssl/pull/3064 and was merged in June 22, 2020.

Thanks,
David Garske, wolfSSL

Share