wolfSSL Manual

Docs -> wolfSSL Manual

Chapter 17: wolfSSL API Reference


17.5  Error Handling and Debugging


The functions in this section have to do with printing and handling errors as well as enabling and disabling debugging in wolfSSL.






CyaSSL_ERR_error_string


Synopsis:

#include <cyassl/ssl.h>


char* CyaSSL_ERR_error_string(unsigned long errNumber, char* data);


Description:

This function converts an error code returned by CyaSSL_get_error() into a more human-readable error string.  errNumber is the error code returned by CyaSSL_get_error() and data is the storage buffer which the error string will be placed in.


The maximum length of data is 80 characters by default, as defined by MAX_ERROR_SZ is cyassl/ctaocrypt/error.h.


Return Values:

On successful completion, this function returns the same string as is returned in data.  Upon failure, this function returns a string with the appropriate failure reason.


Parameters:


errNumber - error code returned by CyaSSL_get_error().


data - output buffer containing human-readable error string matching errNumber.


Example:


int err = 0;

CYASSL* ssl;

char buffer[80];

...

err = CyaSSL_get_error(ssl, 0);

CyaSSL_ERR_error_string(err, buffer);

printf(“err = %d, %s\n”, err, buffer);


See Also:

CyaSSL_get_error

CyaSSL_ERR_error_string_n

CyaSSL_ERR_print_errors_fp

CyaSSL_load_error_strings






CyaSSL_ERR_error_string_n


Synopsis:

#include <cyassl/ssl.h>


void CyaSSL_ERR_error_string_n(unsigned long e, char* buf, unsigned long len);


Description:

This function is a version of CyaSSL_ERR_error_string() where len specifies the maximum number of characters that may be written to buf.  Like CyaSSL_ERR_error_string(), this function converts an error code returned from CyaSSL_get_error() into a more human-readable error string.  The human-readable string is placed in buf.


Return Values:

This function has no return value.


Parameters:


e - error code returned by CyaSSL_get_error().


buff - output buffer containing human-readable error string matching e.


len - maximum length in characters which may be written to buf.


Example:


int err = 0;

CYASSL* ssl;

char buffer[80];

...

err = CyaSSL_get_error(ssl, 0);

CyaSSL_ERR_error_string_n(err, buffer, 80);

printf(“err = %d, %s\n”, err, buffer);


See Also:

CyaSSL_get_error

CyaSSL_ERR_error_string

CyaSSL_ERR_print_errors_fp

CyaSSL_load_error_strings






CyaSSL_ERR_print_errors_fp


Synopsis:

#include <cyassl/ssl.h>


void  CyaSSL_ERR_print_errors_fp(FILE* fp, int err);


Description:

This function converts an error code returned by CyaSSL_get_error() into a more human-readable error string and prints that string to the output file - fp.  err is the error code returned by CyaSSL_get_error() and fp is the file which the error string will be placed in.


Return Values:

This function has no return value.


Parameters:


fp - output file for human-readable error string to be written to.


e - error code returned by CyaSSL_get_error().


Example:


int err = 0;

CYASSL* ssl;

FILE* fp = ...

...

err = CyaSSL_get_error(ssl, 0);

CyaSSL_ERR_print_errors_fp(fp, err);


See Also:

CyaSSL_get_error

CyaSSL_ERR_error_string

CyaSSL_ERR_error_string_n

CyaSSL_load_error_strings






CyaSSL_get_error


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_get_error(CYASSL* ssl, int ret);


Description:

This function returns a unique error code describing why the previous API function call (CyaSSL_connect, CyaSSL_accept, CyaSSL_read, CyaSSL_write, etc.) resulted in an error return code (SSL_FAILURE).  The return value of the previous function is passed to CyaSSL_get_error through ret.


After CyaSSL_get_error is called and returns the unique error code, CyaSSL_ERR_error_string() may be called to get a human-readable error string.  See CyaSSL_ERR_error_string() for more information.


Return Values:

On successful completion, this function will return the unique error code describing why the previous API function failed.


SSL_ERROR_NONE will be returned if ret > 0.


Parameters:


ssl - pointer to the SSL object, created with CyaSSL_new().


ret - return value of the previous function that resulted in an error return code.


Example:


int err = 0;

CYASSL* ssl;

char buffer[80];

...

err = CyaSSL_get_error(ssl, 0);

CyaSSL_ERR_error_string(err, buffer);

printf(“err = %d, %s\n”, err, buffer);


See Also:

CyaSSL_ERR_error_string

CyaSSL_ERR_error_string_n

CyaSSL_ERR_print_errors_fp

CyaSSL_load_error_strings






CyaSSL_load_error_strings


Synopsis:

#include <cyassl/ssl.h>


void CyaSSL_load_error_strings(void);


Description:

This function is for OpenSSL compatibility (SSL_load_error_string) only and takes no action.


Return Values:

This function has no return value.


Parameters:


This function takes no parameters.


Example:


CyaSSL_load_error_strings();


See Also:

CyaSSL_get_error

CyaSSL_ERR_error_string

CyaSSL_ERR_error_string_n

CyaSSL_ERR_print_errors_fp

CyaSSL_load_error_strings






CyaSSL_want_read


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_want_read(CYASSL* ssl)


Description:

This function is similar to calling CyaSSL_get_error() and getting SSL_ERROR_WANT_READ in return.  If the underlying error state is SSL_ERROR_WANT_READ, this function will return 1, otherwise, 0.


Return Values:


1 - CyaSSL_get_error() would return SSL_ERROR_WANT_READ, the underlying I/O has data available for reading.


0 - There is no SSL_ERROR_WANT_READ error state.


Parameters:


ssl - pointer to the SSL session, created with CyaSSL_new().


Example:


int ret;

CYASSL* ssl = 0;

...


ret = CyaSSL_want_read(ssl);

if (ret == 1) {

// underlying I/O has data available for reading (SSL_ERROR_WANT_READ)

}


See Also:

CyaSSL_want_write

CyaSSL_get_error






CyaSSL_want_write


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_want_write(CYASSL* ssl)


Description:

This function is similar to calling CyaSSL_get_error() and getting SSL_ERROR_WANT_WRITE in return.  If the underlying error state is SSL_ERROR_WANT_WRITE, this function will return 1, otherwise, 0.


Return Values:


1 - CyaSSL_get_error() would return SSL_ERROR_WANT_WRITE, the underlying I/O needs data to be written in order for progress to be made in the underlying SSL connection.


0 - There is no SSL_ERROR_WANT_WRITE error state.


Parameters:


ssl - pointer to the SSL session, created with CyaSSL_new().


Example:


int ret;

CYASSL* ssl = 0;

...


ret = CyaSSL_want_write(ssl);

if (ret == 1) {

// underlying I/O needs data to be written (SSL_ERROR_WANT_WRITE)

}


See Also:

CyaSSL_want_read

CyaSSL_get_error






CyaSSL_Debugging_ON


Synopsis:

#include <cyassl/ssl.h>


int  CyaSSL_Debugging_ON(void);


Description:

If logging has been enabled at build time this function turns on logging at runtime.  To enable logging at build time use --enable-debug or define DEBUG_CYASSL


Return Values:

If successful this function will return 0.


NOT_COMPILED_IN is the error that will be returned if logging isn’t enabled for this build.


Parameters:


This function has no parameters.


Example:


CyaSSL_Debugging_ON();


See Also:

CyaSSL_Debugging_OFF

CyaSSL_SetLoggingCb






CyaSSL_Debugging_OFF


Synopsis:

#include <cyassl/ssl.h>


void  CyaSSL_Debugging_OFF(void);


Description:

This function turns off runtime logging messages.  If they’re already off, no action is taken.


Return Values:

No return values are returned by this function.


Parameters:


This function has no parameters.


Example:


CyaSSL_Debugging_OFF();


See Also:

CyaSSL_Debugging_ON

CyaSSL_SetLoggingCb




 

Questions? +1 (425) 245-8247