Input/Output Operation Functions

Functions

int

SSL_set_fd (SSL *ssl, int fd)

Binds the file descriptor fd to the SSL structure ssl. More...

int

SSL_set_rfd (SSL *ssl, int fd)

Sets the file descriptor fd which is used when reading data via the SSL connection ssl. More...

int

SSL_set_wfd (SSL *ssl, int fd)

Sets the file descriptor fd which is used when writing data via the SSL connection ssl. More...

int

SSL_get_fd (SSL *ssl)

Retrieves the file descriptor associated with the read BIO of the SSL connection ssl. More...

void

SSL_set_bio (SSL *ssl, BIO *rbio, BIO *wbio)

Sets the BIOs that will be used for reading and writing data when calling SSL_read() and SSL_write() for the specified SSL connection. More...

BIO*

SSL_get_rbio (SSL *ssl)

Returns a reference to the SSL read BIO. More...

BIO*

SSL_get_wbio (SSL *ssl)

Returns a reference to the SSL write BIO. More...

void

SSL_set_read_ahead (SSL *ssl, int yes)

Sets the read-ahead flag. More...

int

SSL_get_read_ahead (SSL *ssl)

Returns the value of the read-ahead flag. More...

Function Documentation

int SSL_get_fd

(

SSL *

ssl

)

;

Retrieves the file descriptor associated with the read BIO of the SSL connection ssl. The file descriptor is set by a prior call to SSL_set_fd(). The file descriptor may also be set for any BIO structure with a file descriptor created by the SSL.

Parameters:

ssl

[In] The SSL connection reference from which to retrieve the file descriptor.

Returns:: -1 indicates SSL_set_fd() was not called.
<=0 indicates error.

See also:: SSL_set_fd().

Samples:: sock_server.c.

BIO* SSL_get_rbio

(

SSL *

ssl

)

;

Returns a reference to the SSL read BIO. This BIO is used for all read operations during the SSL session.

Parameters:

ssl

[In] The SSL connection reference from which to retrieve the BIO reference.

Returns:: If set, a pointer to the read BIO.
NULL indicates error.

Samples:: bio_client.c, nbio_client.c, and sock_client.c.

int SSL_get_read_ahead

(

SSL *

ssl

)

;

Returns the value of the read-ahead flag. This flag controls whether more data is read from the network than requested (if it is previously determined to be available).

Parameters:

ssl

[In] The SSL connection reference from which to retrieve the read-ahead flag.

Returns:: 0 indicates the flag was not set.
Other value indicates the flag was set.

: By default, SSL-C does not read more data from the network than is required. However if a select call is not used to determine data availability, significant throughput improvement can be gained by switching the read ahead mode on.
Use SSL_pending() to determine whether additional data is available.

BIO* SSL_get_wbio

(

SSL *

ssl

)

;

Returns a reference to the SSL write BIO. This BIO is used for all write operations during the SSL session.

Parameters:

ssl

[In] The SSL structure.

Returns:: If set, a pointer to the write BIO.
NULL indicates error.

void SSL_set_bio	(	SSL *	ssl,
		BIO *	rbio,
		BIO *	wbio
	)	;

Sets the BIOs that will be used for reading and writing data when calling SSL_read() and SSL_write() for the specified SSL connection.

Parameters:

ssl	[In] The SSL connection reference.
rbio	[In] The BIO reference (read).
wbio	[In] The BIO reference (write).

: Existing BIOs for both read and write are removed and freed.
Once the BIO is attached to the SSL, the SSL is responsible for it. Either do not use the BIO pointer again, or increment its reference.
rbio is most commonly set to be the same as wbio. If either rbio or wbio is NULL, the old BIOs are removed.

Example:

SSL *ssl;
BIO *bio;
int fd;
int i_want_to_keep_this_bio;


/* Create/bind/connect a socket */
/* fd = socket(...); */


/* Create an SSL structure */
/* ssl = SSL_new(...); */


/* Create a socket bio and attach the socket fd to it */
bio = BIO_new_socket(fd,BIO_NOCLOSE);

/* Decide if you want the BIO for the all the time */
/* i_want_to_keep_this_bio = .... */


/* Attach the new bio to the SSL structure. This particular
 * call attaches the same socket as the read BIO and the
 * write BIO which is a normal arrangement.
 */
SSL_set_bio(ssl,bio,bio);

/* Once the BIO has been attached to the SSL the SSL takes
 * responsibility for it. Either do not use the BIO pointer
 * again or increment its reference
 */
if (i_want_to_keep_this_bio)
{
        /* Increment the BIO reference so the pointer can
         * be maintained
         */
        BIO_reference_inc(bio);
}
else
{
        /* To be safe, ensure the pointer isn't used again */
        bio = NULL;
}


/* Use the SSL... */


/* Free the SSL structure. This will free the BIO's associated
 * with the SSL. NOTE : Another call to SSL_set_bio() will also
 * free the existing BIO structures.
 */
SSL_free(ssl);


/* If the BIO was maintained, it can still be used. */
if (i_want_to_keep_this_bio)
{
        /* Use the BIO .... */

        /* Free the BIO */
        BIO_free(bio);
        bio = NULL;
}

Samples:: cache_server.c, PKCS11Client.c, sock_server.c, ssl_client.c, and ssl_server.c.

int SSL_set_fd	(	SSL *	ssl,
		int	fd
	)	;

Binds the file descriptor fd to the SSL structure ssl. The descriptor is used by a new socket BIO for read and write calls underpinning both SSL_read() and SSL_write(). Existing read and write BIOs are removed and replaced by a socket BIO.

Parameters:

ssl	[In] The SSL connection reference against which to set the file descriptor.
fd	[In] The file descriptor.

Returns:: 1 indicates success.
0 indicates error.

: This function must reference a socket. Otherwise use SSL_get_wbio() to establish the endpoints.

See also:: SSL_get_fd().

Samples:: fips_client.c, simple.c, and sock_client.c.

void SSL_set_read_ahead	(	SSL *	ssl,
		int	read_ahead
	)	;

Sets the read-ahead flag. This flag controls whether more data is read from the network than requested (if it has been previously determined to be available).

Parameters:

ssl	[In, Out] The SSL connection reference against which to set the read-ahead flag.
read_ahead	[In] The read ahead flag. One of: 0 indicates to not read ahead from the network. 1 indicates to attempt to read ahead if data is available.

: By default, SSL-C does not read more data from the network than is required. However if a select system call is not used to determine data availability, significant throughput improvement can be gained by switching read-ahead mode on.

See also:: SSL_get_read_ahead() and SSL_pending() to determine whether additional data is available.

int SSL_set_rfd	(	SSL *	ssl,
		int	fd
	)	;

Sets the file descriptor fd which is used when reading data via the SSL connection ssl. The descriptor is used by the receive call underpinning SSL_read().

Parameters:

ssl	[In] The SSL connection reference to set the read file descriptor is used by the received call underpinning SSL_read().
fd	[In] The file descriptor.

Returns:: 1 indicates success.
0 indicates error.

: This function must be passed a valid socket descriptor because a socket BIO is created using this descriptor.
Use a BIO interface when using SSL on anything other than sockets.

See also:: SSL_set_fd(), SSL_set_wfd() and SSL_set_bio().

int SSL_set_wfd	(	SSL *	ssl,
		int	fd
	)	;

Sets the file descriptor fd which is used when writing data via the SSL connection ssl. The descriptor is used by the send call underpinning SSL_write().

Parameters:

ssl	[In] The SSL connection reference.
fd	[In] The file descriptor.

Returns:: 1 indicates success.
0 indicates error.

: This function must be passed a valid socket descriptor because a socket BIO is created with this descriptor.
Use a BIO interface when using SSL on anything other than sockets.

See also:: SSL_set_fd(), SSL_set_rfd() and SSL_set_bio().

	RSA BSAFE SSL-C	Security protocol components for C
		Search