Functions
wolfSSL Error Handling and Reporting

Functions

WOLFSSL_API int wolfSSL_Debugging_ON (void)
 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_WOLFSSL. More...
 
WOLFSSL_API void wolfSSL_Debugging_OFF (void)
 This function turns off runtime logging messages. If they’re already off, no action is taken. More...
 
WOLFSSL_API int wolfSSL_get_error (WOLFSSL *, int)
 This function returns a unique error code describing why the previous API function call (wolfSSL_connect, wolfSSL_accept, wolfSSL_read, wolfSSL_write, etc.) resulted in an error return code (SSL_FAILURE). The return value of the previous function is passed to wolfSSL_get_error through ret. After wolfSSL_get_error is called and returns the unique error code, wolfSSL_ERR_error_string() may be called to get a human-readable error string. See wolfSSL_ERR_error_string() for more information. More...
 
WOLFSSL_API void wolfSSL_load_error_strings (void)
 This function is for OpenSSL compatibility (SSL_load_error_string) only and takes no action. More...
 
WOLFSSL_API char * wolfSSL_ERR_error_string (unsigned long, char *)
 This function converts an error code returned by wolfSSL_get_error() into a more human-readable error string. errNumber is the error code returned by wolfSSL_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 wolfssl/wolfcrypt/error.h. More...
 
WOLFSSL_API void wolfSSL_ERR_error_string_n (unsigned long e, char *buf, unsigned long sz)
 This function is a version of wolfSSL_ERR_error_string() where len specifies the maximum number of characters that may be written to buf. Like wolfSSL_ERR_error_string(), this function converts an error code returned from wolfSSL_get_error() into a more human-readable error string. The human-readable string is placed in buf. More...
 
WOLFSSL_API void wolfSSL_ERR_print_errors_fp (FILE *, int err)
 This function converts an error code returned by wolfSSL_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 wolfSSL_get_error() and fp is the file which the error string will be placed in. More...
 
WOLFSSL_API int wolfSSL_want_read (WOLFSSL *)
 This function is similar to calling wolfSSL_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. More...
 
WOLFSSL_API int wolfSSL_want_write (WOLFSSL *)
 This function is similar to calling wolfSSL_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. More...
 
WOLFSSL_API unsigned long wolfSSL_ERR_peek_last_error (void)
 This function returns the absolute value of the last error from WOLFSSL_ERROR encountered. More...
 

Detailed Description

Function Documentation

◆ wolfSSL_Debugging_OFF()

WOLFSSL_API void wolfSSL_Debugging_OFF ( void  )

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

Returns
none No returns.
Parameters
noneNo parameters.

Example

See also
wolfSSL_Debugging_ON
wolfSSL_SetLoggingCb

◆ wolfSSL_Debugging_ON()

WOLFSSL_API int wolfSSL_Debugging_ON ( void  )

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_WOLFSSL.

Returns
0 upon success.
NOT_COMPILED_IN is the error that will be returned if logging isn’t enabled for this build.
Parameters
noneNo parameters.

Example

See also
wolfSSL_Debugging_OFF
wolfSSL_SetLoggingCb

◆ wolfSSL_ERR_error_string()

WOLFSSL_API char* wolfSSL_ERR_error_string ( unsigned  long,
char *   
)

This function converts an error code returned by wolfSSL_get_error() into a more human-readable error string. errNumber is the error code returned by wolfSSL_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 wolfssl/wolfcrypt/error.h.

Returns
success On successful completion, this function returns the same string as is returned in data.
failure Upon failure, this function returns a string with the appropriate failure reason, msg.
Parameters
errNumbererror code returned by wolfSSL_get_error().
dataoutput buffer containing human-readable error string matching errNumber.

Example

int err = 0;
WOLFSSL* ssl;
char buffer[80];
...
err = wolfSSL_get_error(ssl, 0);
printf(“err = %d, %s\n”, err, buffer);
See also
wolfSSL_get_error
wolfSSL_ERR_error_string_n
wolfSSL_ERR_print_errors_fp
wolfSSL_load_error_strings

◆ wolfSSL_ERR_error_string_n()

WOLFSSL_API void wolfSSL_ERR_error_string_n ( unsigned long  e,
char *  buf,
unsigned long  sz 
)

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

Returns
none No returns.
Parameters
eerror code returned by wolfSSL_get_error().
buffoutput buffer containing human-readable error string matching e.
lenmaximum length in characters which may be written to buf.

Example

int err = 0;
WOLFSSL* ssl;
char buffer[80];
...
err = wolfSSL_get_error(ssl, 0);
wolfSSL_ERR_error_string_n(err, buffer, 80);
printf(“err = %d, %s\n”, err, buffer);
See also
wolfSSL_get_error
wolfSSL_ERR_error_string
wolfSSL_ERR_print_errors_fp
wolfSSL_load_error_strings

◆ wolfSSL_ERR_peek_last_error()

WOLFSSL_API unsigned long wolfSSL_ERR_peek_last_error ( void  )

This function returns the absolute value of the last error from WOLFSSL_ERROR encountered.

Returns
error Returns absolute value of last error.
Parameters
noneNo parameters.

Example

unsigned long err;
...
// inspect err value
See also
wolfSSL_ERR_print_errors_fp

◆ wolfSSL_ERR_print_errors_fp()

WOLFSSL_API void wolfSSL_ERR_print_errors_fp ( FILE *  ,
int  err 
)

This function converts an error code returned by wolfSSL_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 wolfSSL_get_error() and fp is the file which the error string will be placed in.

Returns
none No returns.
Parameters
fpoutput file for human-readable error string to be written to.
errerror code returned by wolfSSL_get_error().

Example

int err = 0;
WOLFSSL* ssl;
FILE* fp = ...
...
err = wolfSSL_get_error(ssl, 0);
See also
wolfSSL_get_error
wolfSSL_ERR_error_string
wolfSSL_ERR_error_string_n
wolfSSL_load_error_strings

◆ wolfSSL_get_error()

WOLFSSL_API int wolfSSL_get_error ( WOLFSSL ,
int   
)

This function returns a unique error code describing why the previous API function call (wolfSSL_connect, wolfSSL_accept, wolfSSL_read, wolfSSL_write, etc.) resulted in an error return code (SSL_FAILURE). The return value of the previous function is passed to wolfSSL_get_error through ret. After wolfSSL_get_error is called and returns the unique error code, wolfSSL_ERR_error_string() may be called to get a human-readable error string. See wolfSSL_ERR_error_string() for more information.

Returns
code 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
sslpointer to the SSL object, created with wolfSSL_new().
retreturn value of the previous function that resulted in an error return code.

Example

int err = 0;
WOLFSSL* ssl;
char buffer[80];
...
err = wolfSSL_get_error(ssl, 0);
printf(“err = %d, %s\n”, err, buffer);
See also
wolfSSL_ERR_error_string
wolfSSL_ERR_error_string_n
wolfSSL_ERR_print_errors_fp
wolfSSL_load_error_strings

◆ wolfSSL_load_error_strings()

WOLFSSL_API void wolfSSL_load_error_strings ( void  )

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

Returns
none No returns.
Parameters
noneNo parameters.

Example

See also
wolfSSL_get_error
wolfSSL_ERR_error_string
wolfSSL_ERR_error_string_n
wolfSSL_ERR_print_errors_fp
wolfSSL_load_error_strings

◆ wolfSSL_want_read()

WOLFSSL_API int wolfSSL_want_read ( WOLFSSL )

This function is similar to calling wolfSSL_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.

Returns
1 wolfSSL_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
sslpointer to the SSL session, created with wolfSSL_new().

Example

int ret;
WOLFSSL* ssl = 0;
...
ret = wolfSSL_want_read(ssl);
if (ret == 1) {
// underlying I/O has data available for reading (SSL_ERROR_WANT_READ)
}
See also
wolfSSL_want_write
wolfSSL_get_error

◆ wolfSSL_want_write()

WOLFSSL_API int wolfSSL_want_write ( WOLFSSL )

This function is similar to calling wolfSSL_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.

Returns
1 wolfSSL_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
sslpointer to the SSL session, created with wolfSSL_new().

Example

int ret;
WOLFSSL* ssl = 0;
...
ret = wolfSSL_want_write(ssl);
if (ret == 1) {
// underlying I/O needs data to be written (SSL_ERROR_WANT_WRITE)
}
See also
wolfSSL_want_read
wolfSSL_get_error