My Project
Functions
wolfSSL Error Handling and Reporting

Functions

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...
 
void wolfSSL_Debugging_OFF (void)
 This function turns off runtime logging messages. If they’re already off, no action is taken. More...
 
int wolfSSL_get_error (WOLFSSL *ssl, int ret)
 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...
 
void wolfSSL_load_error_strings (void)
 This function is for OpenSSL compatibility (SSL_load_error_string) only and takes no action. More...
 
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...
 
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...
 
void wolfSSL_ERR_print_errors_fp (XFILE fp, 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...
 
void wolfSSL_ERR_print_errors_cb (int(*cb)(const char *str, size_t len, void *u), void *u)
 This function uses the provided callback to handle error reporting. The callback function is executed for each error line. The string, length, and userdata are passed into the callback parameters. More...
 
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...
 
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...
 
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()

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()

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()

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()

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()

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_cb()

void wolfSSL_ERR_print_errors_cb ( int(*)(const char *str, size_t len, void *u)  cb,
void *  u 
)

This function uses the provided callback to handle error reporting. The callback function is executed for each error line. The string, length, and userdata are passed into the callback parameters.

Returns
none No returns.
Parameters
cbthe callback function.
uuserdata to pass into the callback function.

Example

int error_cb(const char *str, size_t len, void *u)
{ fprintf((FILE*)u, "%-*.*s\n", (int)len, (int)len, str); return 0; }
...
FILE* fp = ...
wolfSSL_ERR_print_errors_cb(error_cb, fp);
See also
wolfSSL_get_error
wolfSSL_ERR_error_string
wolfSSL_ERR_error_string_n
wolfSSL_load_error_strings

◆ wolfSSL_ERR_print_errors_fp()

void wolfSSL_ERR_print_errors_fp ( XFILE  fp,
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()

int wolfSSL_get_error ( WOLFSSL *  ssl,
int  ret 
)

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
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. For ret <= 0, there are some cases when this value can also be returned when a previous API appeared to return an error code but no error actually occurred. An example is calling wolfSSL_read() with a zero sz parameter. A 0 return from wolfSSL_read() usually indicates an error but in this case no error occurred. If wolfSSL_get_error() is called afterwards, SSL_ERROR_NONE will be returned.
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()

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()

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()

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
wolfSSL_ERR_peek_last_error
unsigned long wolfSSL_ERR_peek_last_error(void)
This function returns the absolute value of the last error from WOLFSSL_ERROR encountered.
wolfSSL_load_error_strings
void wolfSSL_load_error_strings(void)
This function is for OpenSSL compatibility (SSL_load_error_string) only and takes no action.
wolfSSL_want_write
int wolfSSL_want_write(WOLFSSL *)
This function is similar to calling wolfSSL_get_error() and getting SSL_ERROR_WANT_WRITE in return....
wolfSSL_ERR_error_string_n
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 ch...
wolfSSL_want_read
int wolfSSL_want_read(WOLFSSL *)
This function is similar to calling wolfSSL_get_error() and getting SSL_ERROR_WANT_READ in return....
wolfSSL_ERR_print_errors_fp
void wolfSSL_ERR_print_errors_fp(XFILE fp, int err)
This function converts an error code returned by wolfSSL_get_error() into a more human-readable error...
wolfSSL_Debugging_ON
int wolfSSL_Debugging_ON(void)
If logging has been enabled at build time this function turns on logging at runtime....
wolfSSL_Debugging_OFF
void wolfSSL_Debugging_OFF(void)
This function turns off runtime logging messages. If they’re already off, no action is taken.
wolfSSL_get_error
int wolfSSL_get_error(WOLFSSL *ssl, int ret)
This function returns a unique error code describing why the previous API function call (wolfSSL_conn...
wolfSSL_ERR_error_string
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...