RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

Input/Output Operation Functions

This section details the input and output operation functions associated with the SSL connection. For example, these functions perform the handshake if required and enable applications to read and write data over the connection.

Functions

int R_CDECL SSL_set_fd (SSL *ssl, int fd)
 Binds the file descriptor fd to the SSL structure ssl. More...

int R_CDECL 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 R_CDECL 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 R_CDECL SSL_get_fd (SSL *ssl)
 Retrieves the file descriptor associated with the read BIO of the SSL connection ssl. More...

void R_CDECL 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 value for the SSL structure. More...

int SSL_get_read_ahead (SSL *ssl)
 Returns the read ahead flag value from the SSL structure. More...

Function Documentation

int R_CDECL 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, and ssl_client.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 read BIO reference.
Returns:
A pointer to the read BIO, if set.
Otherwise NULL.
note.gif
ssl is not NULL.
See also:
SSL_get_wbio() and SSL_set_bio().
Samples:
bio_client.c, nbio_client.c, and sock_client.c.

int SSL_get_read_ahead (  SSL *    ssl )  ;
 

Returns the read ahead flag value from the SSL structure. SSL_get_read_ahead() returns the status of the read ahead flag by directly accessing the SSL structure. The read ahead flag controls whether more data is read from the network than requested (if it is previously determined to be available). This option can be used to achieve significant throughput improvement.

Parameters:
ssl [In] The SSL structure against which read ahead flag is to be returned.
Returns:
0 indicates the flag is not set.
Other values indicate the flag is set.
note.gif
The read ahead flag is set to 0 by default. By default, SSL 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 read ahead mode on.
See also:
SSL_pending() and SSL_set_read_ahead().

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 connection reference from which to set the write BIO reference.
Returns:
A pointer to the write BIO if set.
Otherwise NULL.
note.gif
ssl is not NULL.

void R_CDECL 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).
note.gif
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, p7ssl_client.c, p7ssl_server.c, sock_server.c, ssl_client.c, and ssl_server.c.

int R_CDECL 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.
note.gif
This function must reference a socket. Otherwise use SSL_get_wbio() to establish the endpoints.
See also:
SSL_get_fd().
Samples:
simple.c, and sock_client.c.

void SSL_set_read_ahead (  SSL *    ssl,
int    yes
)  ;
 

Sets the read ahead flag value for the SSL structure. SSL_set_read_ahead() sets the read ahead flag by directly accessing the SSL structure. The read ahead flag controls whether more data is read from the network than requested (if it is previously determined to be available). This option can be used to achieve significant throughput improvement.

Parameters:
ssl [In] The SSL structure against which to set the read ahead flag.
yes [In] The read ahead flag. One of:
  • = 0 to clear the flag.
  • > 0 to set the flag.
    • note.gif
    Ensure that ssl is not NULL. By default, ssl 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 the read ahead mode on.
    See also:
    SSL_pending() and SSL_get_read_ahead().

    int R_CDECL 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.
    note.gif
    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 R_CDECL 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.
    note.gif
    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().

    Copyright (c) 1999-2005 RSA Security Inc. All rights reserved. 072-001001-2100-001-000 - 2.1