wolfSSL Manual

Docs -> wolfSSL Manual

Chapter 17: wolfSSL API Reference


17.8  Connection, Session, and I/O


The functions in this section deal with setting up the SSL/TLS connection, managing SSL sessions, and input/output.






CyaSSL_accept


Synopsis:

#include <cyassl/ssl.h>


int  CyaSSL_accept(CYASSL* ssl);


Description:

This function is called on the server side and waits for an SSL client to initiate the SSL/TLS handshake.  When this function is called, the underlying communication channel has already been set up.


CyaSSL_accept() works with both blocking and non-blocking I/O.  When the underlying I/O is non-blocking, CyaSSL_accept() will return when the underlying I/O could not satisfy the needs of of CyaSSL_accept to continue the handshake.  In this case, a call to CyaSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.  The calling process must then repeat the call to CyaSSL_accept when data is available to read and CyaSSL will pick up where it left off. When using a non-blocking socket, nothing needs to be done, but select() can be used to check for the required condition.


If the underlying I/O is blocking, CyaSSL_accept() will only return once the handshake has been finished or an error occurred.


Return Values:

If successful the call will return SSL_SUCCESS.


SSL_FATAL_ERROR will be returned if an error occurred.  To get a more detailed error code, call CyaSSL_get_error().


Parameters:


ssl - a pointer to a CYASSL structure, created using CyaSSL_new().


Example:


int ret = 0;

int err = 0;

CYASSL* ssl;

char buffer[80];

...


ret = CyaSSL_accept(ssl);

if (ret != SSL_SUCCESS) {

err = CyaSSL_get_error(ssl, ret);

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


See Also:

CyaSSL_get_error

CyaSSL_connect






CyaSSL_connect


Synopsis:

#include <cyassl/ssl.h>


int  CyaSSL_connect(CYASSL* ssl);


Description:

This function is called on the client side and initiates an SSL/TLS handshake with a server.  When this function is called, the underlying communication channel has already been set up.


CyaSSL_connect() works with both blocking and non-blocking I/O.  When the underlying I/O is non-blocking, CyaSSL_connect() will return when the underlying I/O could not satisfy the needs of of CyaSSL_connect to continue the handshake.  In this case, a call to CyaSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.  The calling process must then repeat the call to CyaSSL_connect() when the underlying I/O is ready and CyaSSL will pick up where it left off. When using a non-blocking socket, nothing needs to be done, but select() can be used to check for the required condition.


If the underlying I/O is blocking, CyaSSL_connect() will only return once the handshake has been finished or an error occurred.


CyaSSL takes a different approach to certificate verification than OpenSSL does.  The default policy for the client is to verify the server, this means that if you don't load CAs to verify the server you'll get a connect error, unable to verify (-155).  It you want to mimic OpenSSL behavior of having SSL_connect succeed even if verifying the server fails and reducing security you can do this by calling:


SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0);


before calling SSL_new();  Though it's not recommended.



Return Values:

If successful the call will return SSL_SUCCESS.


SSL_FATAL_ERROR will be returned if an error occurred.  To get a more detailed error code, call CyaSSL_get_error().


Parameters:


ssl - a pointer to a CYASSL structure, created using CyaSSL_new().


Example:


int ret = 0;

int err = 0;

CYASSL* ssl;

char buffer[80];

...


ret = CyaSSL_connect(ssl);

if (ret != SSL_SUCCESS) {

err = CyaSSL_get_error(ssl, ret);

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


See Also:

CyaSSL_get_error

CyaSSL_accept






CyaSSL_connect_cert


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_connect_cert(CYASSL* ssl);


Description:

This function is called on the client side and initiates an SSL/TLS handshake with a server only long enough to get the peer’s certificate chain.  When this function is called, the underlying communication channel has already been set up.


CyaSSL_connect_cert() works with both blocking and non-blocking I/O.  When the underlying I/O is non-blocking, CyaSSL_connect_cert() will return when the underlying I/O could not satisfy the needs of of CyaSSL_connect_cert() to continue the handshake.  In this case, a call to CyaSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.  The calling process must then repeat the call to CyaSSL_connect_cert() when the underlying I/O is ready and CyaSSL will pick up where it left off. When using a non-blocking socket, nothing needs to be done, but select() can be used to check for the required condition.


If the underlying I/O is blocking, CyaSSL_connect_cert() will only return once the peer’s certificate chain has been received.


Return Values:

If successful the call will return SSL_SUCCESS.


SSL_FAILURE will be returned if the SSL session parameter is NULL.


SSL_FATAL_ERROR will be returned if an error occurred.  To get a more detailed error code, call CyaSSL_get_error().


Parameters:


ssl - a pointer to a CYASSL structure, created using CyaSSL_new().


Example:


int ret = 0;

int err = 0;

CYASSL* ssl;

char buffer[80];

...


ret = CyaSSL_connect_cert(ssl);

if (ret != SSL_SUCCESS) {

err = CyaSSL_get_error(ssl, ret);

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


See Also:

CyaSSL_get_error

CyaSSL_connect

CyaSSL_accept






CyaSSL_get_fd


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_get_fd(const CYASSL* ssl);


Description:

This function returns the file descriptor (fd) used as the input/output facility for the SSL connection.  Typically this will be a socket file descriptor.


Return Values:

If successful the call will return the SSL session file descriptor.


Parameters:


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


Example:


int sockfd;

CYASSL* ssl = 0;

...

sockfd = CyaSSL_get_fd(ssl);

...


See Also:

CyaSSL_set_fd






CyaSSL_get_session


Synopsis:

#include <cyassl/ssl.h>


CYASSL_SESSION* CyaSSL_get_session(CYASSL* ssl);


Description:

This function returns a pointer to the current session (CYASSL_SESSION) used in ssl.  The CYASSL_SESSION pointed to contains all the necessary information required to perform a session resumption and reestablish the connection without a new handshake.


For session resumption, before calling CyaSSL_shutdown() with your session object, an application should save the session ID from the object with a call to CyaSSL_get_session(), which returns a pointer to the session.  Later, the application should create a new CYASSL object and assign the saved session with CyaSSL_set_session().  At this point, the application may call CyaSSL_connect() and CyaSSL will try to resume the session.  The CyaSSL server code allows session resumption by default.


Return Values:

If successful the call will return a pointer to the the current SSL session object.


NULL will be returned if ssl is NULL, the SSL session cache is disabled, CyaSSL doesn’t have the Session ID available, or mutex functions fail.


Parameters:


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


Example:


CYASSL* ssl = 0;

CYASSL_SESSION* session = 0;

...

session = CyaSSL_get_session(ssl);

if (session == NULL) {

// failed to get session pointer

}

...


See Also:

CyaSSL_set_session






CyaSSL_get_using_nonblock


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_get_using_nonblock(CYASSL* ssl);


Description:

This function allows the application to determine if CyaSSL is using non-blocking I/O.  If CyaSSL is using non-blocking I/O, this function will return 1, otherwise 0.


After an application creates a CYASSL object, if it will be used with a non-blocking socket, call CyaSSL_set_using_nonblock() on it. This lets the CYASSL object know that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out.


Return Values:


0 - underlying I/O is blocking.


1 - underlying I/O is non-blocking


Parameters:


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


Example:


int ret = 0;

CYASSL* ssl = 0;

...

ret = CyaSSL_get_using_nonblock(ssl);

if (ret == 1) {

// underlying I/O is non-blocking

}

...


See Also:

CyaSSL_set_session






CyaSSL_flush_sessions


Synopsis:

#include <cyassl/ssl.h>


void CyaSSL_flush_sessions(CYASSL_CTX *ctx, long tm);


Description:

This function flushes session from the session cache which have expired.  The time, tm, is used for the time comparison.


Note that CyaSSL currently uses a static table for sessions, so no flushing is needed.  As such, this function is currently just a stub.  This function provides OpenSSL compatibility (SSL_flush_sessions) when CyaSSL is compiled with the OpenSSL compatibility layer.


Return Values:

This function does not have a return value.


Parameters:


ctx - a pointer to a CYASSL_CTX structure, created using CyaSSL_CTX_new().


tm - time used in session expiration comparison.


Example:


CYASSL_CTX* ssl;

...


CyaSSL_flush_sessions(ctx, time(0));


See Also:

CyaSSL_get_session

CyaSSL_set_session






CyaSSL_negotiate


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_negotiate(CYASSL* ssl);


Description:

Performs the actual connect or accept based on the side of the SSL method.  If called from the client side then an CyaSSL_connect() is done while a CyaSSL_accept() is performed if called from the server side.


Return Values:

SSL_SUCCESS will be returned if successful. (Note, older versions will return 0.)


SSL_FATAL_ERROR will be returned if the underlying call resulted in an error. Use CyaSSL_get_error() to get a specific error code.


Parameters:


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


Example:


int ret = SSL_FATAL_ERROR;

CYASSL* ssl = 0;

...

ret = CyaSSL_negotiate(ssl);

if (ret == SSL_FATAL_ERROR) {

// SSL establishment failed

int error_code = CyaSSL_get_error(ssl);

...

}

...


See Also:

SSL_connect

SSL_accept






CyaSSL_peek


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_peek(CYASSL* ssl, void* data, int sz);


Description:

This function copies sz bytes from the SSL session (ssl) internal read buffer into the buffer data.  This function is identical to CyaSSL_read() except that the data in the internal SSL session receive buffer is not removed or modified.


If necessary, like CyaSSL_read(), CyaSSL_peek() will negotiate an SSL/TLS session if the handshake has not already been performed yet by CyaSSL_connect() or CyaSSL_accept().


The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max record size can be controlled by the MAX_RECORD_SIZE define in <cyassl_root>/cyassl/internal.h).  As such, CyaSSL needs to read an entire SSL record internally before it is able to process and decrypt the record.  Because of this, a call to CyaSSL_peek() will only be able to return the maximum buffer size which has been decrypted at the time of calling.  There may be additional not-yet-decrypted data waiting in the internal CyaSSL receive buffer which will be retrieved and decrypted with the next call to CyaSSL_peek() / CyaSSL_read().


If sz is larger than the number of bytes in the internal read buffer, SSL_peek() will return the bytes available in the internal read buffer.  If no bytes are buffered in the internal read buffer yet, a call to CyaSSL_peek() will trigger processing of the next record.


Return Values:


> 0 - the number of bytes read upon success.


0 - will be returned upon failure.  This may be caused by a either a clean (close notify alert) shutdown or just that the peer closed the connection.  Call CyaSSL_get_error() for the specific error code.


SSL_FATAL_ERROR - will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call CyaSSL_peek() again.  Use CyaSSL_get_error() to get a specific error code.



Parameters:


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


data - buffer where CyaSSL_peek() will place data read.


sz - number of bytes to read into data.


Example:


CYASSL* ssl = 0;

char reply[1024];

...


input = CyaSSL_peek(ssl, reply, sizeof(reply));

if (input > 0) {

// “input” number of bytes returned into buffer “reply”

}


See Also:

CyaSSL_read






CyaSSL_pending


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_pending(CYASSL* ssl);


Description:

This function returns the number of bytes which are buffered and available in the SSL object to be read by CyaSSL_read().


Return Values:


This function returns the number of bytes pending.


Parameters:


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


Example:


int pending = 0;

CYASSL* ssl = 0;

...


pending = CyaSSL_pending(ssl);

printf(“There are %d bytes buffered and available for reading”, pending);


See Also:

CyaSSL_recv

CyaSSL_read

CyaSSL_peek






CyaSSL_read


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_read(CYASSL* ssl, void* data, int sz);


Description:

This function reads sz bytes from the SSL session (ssl) internal read buffer into the buffer data.  The bytes read are removed from the internal receive buffer.


If necessary CyaSSL_read() will negotiate an SSL/TLS session if the handshake has not already been performed yet by CyaSSL_connect() or CyaSSL_accept().


The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max record size can be controlled by the MAX_RECORD_SIZE define in <cyassl_root>/cyassl/internal.h).  As such, CyaSSL needs to read an entire SSL record internally before it is able to process and decrypt the record.  Because of this, a call to CyaSSL_read() will only be able to return the maximum buffer size which has been decrypted at the time of calling.  There may be additional not-yet-decrypted data waiting in the internal CyaSSL receive buffer which will be retrieved and decrypted with the next call to CyaSSL_read().


If sz is larger than the number of bytes in the internal read buffer, SSL_read() will return the bytes available in the internal read buffer.  If no bytes are buffered in the internal read buffer yet, a call to CyaSSL_read() will trigger processing of the next record.


Return Values:


> 0 - the number of bytes read upon success.


0 - will be returned upon failure.  This may be caused by a either a clean (close notify alert) shutdown or just that the peer closed the connection.  Call CyaSSL_get_error() for the specific error code.


SSL_FATAL_ERROR - will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call CyaSSL_read() again.  Use CyaSSL_get_error() to get a specific error code.



Parameters:


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


data - buffer where CyaSSL_read() will place data read.


sz - number of bytes to read into data.


Example:


CYASSL* ssl = 0;

char reply[1024];

...


input = CyaSSL_read(ssl, reply, sizeof(reply));

if (input > 0) {

// “input” number of bytes returned into buffer “reply”

}


See CyaSSL examples (client, server, echoclient, echoserver) for more complete examples of CyaSSL_read().


See Also:

CyaSSL_recv

CyaSSL_write

CyaSSL_peek

CyaSSL_pending






CyaSSL_recv


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_recv(CYASSL* ssl, void* data, int sz, int flags);


Description:

This function reads sz bytes from the SSL session (ssl) internal read buffer into the buffer data using the specified flags for the underlying recv operation.  The bytes read are removed from the internal receive buffer.  This function is identical to CyaSSL_read() except that it allows the application to set the recv flags for the underlying read operation.


If necessary CyaSSL_recv() will negotiate an SSL/TLS session if the handshake has not already been performed yet by CyaSSL_connect() or CyaSSL_accept().


The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max record size can be controlled by the MAX_RECORD_SIZE define in <cyassl_root>/cyassl/internal.h).  As such, CyaSSL needs to read an entire SSL record internally before it is able to process and decrypt the record.  Because of this, a call to CyaSSL_recv() will only be able to return the maximum buffer size which has been decrypted at the time of calling.  There may be additional not-yet-decrypted data waiting in the internal CyaSSL receive buffer which will be retrieved and decrypted with the next call to CyaSSL_recv().


If sz is larger than the number of bytes in the internal read buffer, SSL_recv() will return the bytes available in the internal read buffer.  If no bytes are buffered in the internal read buffer yet, a call to CyaSSL_recv() will trigger processing of the next record.


Return Values:


> 0 - the number of bytes read upon success.


0 - will be returned upon failure.  This may be caused by a either a clean (close notify alert) shutdown or just that the peer closed the connection.  Call CyaSSL_get_error() for the specific error code.


SSL_FATAL_ERROR - will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call CyaSSL_recv() again.  Use CyaSSL_get_error() to get a specific error code.



Parameters:


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


data - buffer where CyaSSL_recv() will place data read.


sz - number of bytes to read into data.


flags - the recv flags to use for the underlying recv operation.


Example:


CYASSL* ssl = 0;

char reply[1024];

int flags = ... ;

...


input = CyaSSL_recv(ssl, reply, sizeof(reply), flags);

if (input > 0) {

// “input” number of bytes returned into buffer “reply”

}


See Also:

CyaSSL_read

CyaSSL_write

CyaSSL_peek

CyaSSL_pending






CyaSSL_send


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_send(CYASSL* ssl, const void* data, int sz, int flags);


Description:

This function writes sz bytes from the buffer, data, to the SSL connection, ssl, using the specified flags for the underlying write operation.


If necessary CyaSSL_send() will negotiate an SSL/TLS session if the handshake has not already been performed yet by CyaSSL_connect() or CyaSSL_accept().


CyaSSL_send() works with both blocking and non-blocking I/O.  When the underlying I/O is non-blocking, CyaSSL_send() will return when the underlying I/O could not satisfy the needs of of CyaSSL_send to continue.  In this case, a call to CyaSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.  The calling process must then repeat the call to CyaSSL_send() when the underlying I/O is ready.


If the underlying I/O is blocking, CyaSSL_send() will only return once the buffer data of size sz has been completely written or an error occurred.


Return Values:


> 0 - the number of bytes written upon success.


0 - will be returned upon failure.  Call CyaSSL_get_error() for the specific error code.


SSL_FATAL_ERROR - will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call CyaSSL_send() again.  Use CyaSSL_get_error() to get a specific error code.



Parameters:


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


data - data buffer to send to peer.


sz - size, in bytes, of data to be sent to peer.


flags - the send flags to use for the underlying send operation.


Example:


CYASSL* ssl = 0;

char msg[64] = “hello cyassl!”;

int msgSz = (int)strlen(msg);

int flags = ... ;

...


input = CyaSSL_send(ssl, msg, msgSz, flags);

if (input != msgSz) {

// CyaSSL_send() failed

}


See Also:

CyaSSL_write

CyaSSL_read

CyaSSL_recv






CyaSSL_write


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_write(CYASSL* ssl, const void* data, int sz);


Description:

This function writes sz bytes from the buffer, data, to the SSL connection, ssl.


If necessary, CyaSSL_write() will negotiate an SSL/TLS session if the handshake has not already been performed yet by CyaSSL_connect() or CyaSSL_accept().


CyaSSL_write() works with both blocking and non-blocking I/O.  When the underlying I/O is non-blocking, CyaSSL_write() will return when the underlying I/O could not satisfy the needs of of CyaSSL_write() to continue.  In this case, a call to CyaSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.  The calling process must then repeat the call to CyaSSL_write() when the underlying I/O is ready.


If the underlying I/O is blocking, CyaSSL_write() will only return once the buffer data of size sz has been completely written or an error occurred.


Return Values:


> 0 - the number of bytes written upon success.


0 - will be returned upon failure.  Call CyaSSL_get_error() for the specific error code.


SSL_FATAL_ERROR - will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call CyaSSL_write() again.  Use CyaSSL_get_error() to get a specific error code.


Parameters:


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


data - data buffer which will be sent to peer.


sz - size, in bytes, of data to send to the peer (data).


Example:


CYASSL* ssl = 0;

char msg[64] = “hello cyassl!”;

int msgSz = (int)strlen(msg);

int flags;

int ret;

...


ret = CyaSSL_write(ssl, msg, msgSz);

if (ret <= 0) {

// CyaSSL_write() failed, call CyaSSL_get_error()

}


See CyaSSL examples (client, server, echoclient, echoserver) for more more detailed examples of CyaSSL_write().


See Also:

CyaSSL_send

CyaSSL_read

CyaSSL_recv






CyaSSL_writev


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_writev(CYASSL* ssl, const struct iovec* iov, int iovcnt);


Description:

Simulates writev semantics but doesn’t actually do block at a time because of SSL_write() behavior and because front adds may be small.  Makes porting into software that uses writev easier.


Return Values:


> 0 - the number of bytes written upon success.


0 - will be returned upon failure.  Call CyaSSL_get_error() for the specific error code.


MEMORY_ERROR will be returned if a memory error was encountered.


SSL_FATAL_ERROR - will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call CyaSSL_write() again.  Use CyaSSL_get_error() to get a specific error code.


Parameters:


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


iov - array of I/O vectors to write


iovcnt - number of vectors in iov array.


Example:


CYASSL* ssl = 0;

char *bufA = “hello\n”;

char *bufB = “hello world\n”;

int iovcnt;

struct iovec iov[2];


iov[0].iov_base = buffA;

iov[0].iov_len = strlen(buffA);

iov[1].iov_base = buffB;

iov[1].iov_len = strlen(buffB);

iovcnt = 2;

...


ret = CyaSSL_writev(ssl, iov, iovcnt);

// wrote “ret” bytes, or error if <= 0.


See Also:

CyaSSL_write




 

Questions? +1 (425) 245-8247