RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

Structure Functions

This section documents the functions that facilitate the BIO structure.

Functions

long * BIO_set_conn_hostname (BIO *bio, char *name)
 Sets the host name value name for the connection BIO bio when using a UDP or TCP-based BIO. More...

long * BIO_set_conn_port (BIO *bio, char *port)
 Sets the port value port for the connection BIO bio. More...

long * BIO_set_conn_ip (BIO *bio, char *ip)
 Sets the IP address value ip for the connection BIO bio. More...

long * BIO_set_conn_int_port (BIO *bio, int port)
 Sets the port value port for the connection BIO bio. More...

char * BIO_get_conn_hostname (BIO *bio)
 Returns a pointer to the host name for the connection BIO bio. More...

char * BIO_get_conn_port (BIO *bio)
 Returns the port value for the connection BIO bio as a string. More...

char * BIO_get_conn_ip (BIO *bio)
 Returns the IP address for the connection BIO bio. More...

long BIO_get_conn_int_port (BIO *bio, int *portp)
 Returns the port number for the connection BIO bio. More...

long BIO_set_nbio (BIO *bio, int nb_flag)
 Sets the I/O of the underlying connection to blocking or non-blocking BIO bio. More...

char * BIO_set_accept_port (BIO *bio, char *name)
 Sets the port information for the accept socket of the server. More...

char * BIO_get_accept_port (BIO *bio)
 Returns the port information for the accept socket of the server. More...

long BIO_set_nbio_accept (BIO *accept_bio, int nb_flag)
 Sets to blocking or non-blocking I/O of the underlying connection BIO bio. More...

long BIO_set_accept_bios (BIO *accept_bio, BIO *template_bio)
 Sets the template BIO template_bio that is automatically duplicated when a successful connection occurs on accept_bio. More...

long BIO_set_bind_mode (BIO *bio, int mode)
 Sets the relevant TCP/IP flag allowing a socket to be re-bound. More...

long BIO_get_bind_mode (BIO *bio)
 Returns the relevant TCP/IP flag for the BIO bio indicating whether a socket can be re-bound. More...

int BIO_do_connect (BIO *bio)
 Sets up a client side connection socket on the connect BIO bio. More...

int BIO_do_accept (BIO *bio)
 Sets up a service side socket that accepts an incoming socket connection on the accept BIO bio. More...

int BIO_do_handshake (BIO *bio)
 Attempts to perform the next state in a BIO handshake for BIOs containing state engines. More...

long BIO_set_fd (BIO *bio, int fd, int close_flag)
 Sets the read file descriptor fd to be associated with the BIO bio. More...

long BIO_get_fd (BIO *bio, char *fd)
 Retrieves the read file descriptor fd associated with the BIO bio. More...

long BIO_set_ssl (BIO *bio, SSL *ssl, int close_flag)
 Sets the SSL structure ssl for the BIO bio. More...

long BIO_get_ssl (BIO *bio, SSL **sslp)
 Returns the SSL structure for the SSL BIO bio. More...

long BIO_set_ssl_mode (BIO *bio, int client)
 Sets the connection state client of the SSL for the BIO bio. More...

int BIO_set_ssl_renegotiate_bytes (BIO *bio, int num)
 Sets the number of Bytes that are sent between renegotiations for the SSL BIO bio. More...

int BIO_set_ssl_renegotiate_timeout (BIO *bio, int seconds)
 Sets the renegotiation period for the SSL BIO bio. More...

int BIO_set_mem_eof_return (BIO *bio, long v)
 Sets the BIO bio End Of File (EOF) status. More...

int BIO_get_buffer_num_lines (BIO *bio)
 Returns the number of lines in buffer BIO bio. More...

int BIO_set_buffer_size (BIO *bio, long size)
 Sets the buffer size of BIO bio. More...

int BIO_set_read_buffer_size (BIO *bio, long size)
 Sets the read buffer size of BIO bio. More...

int BIO_set_write_buffer_size (BIO *bio, long size)
 Sets the write buffer size of BIO bio. More...

int BIO_set_buffer_read_data (BIO *bio, char *buf, long num)
 Sets the buffer read data for BIO bio. More...

int BIO_reset (BIO *bio)
 Resets the BIO bio to its initial state. More...

int BIO_eof (BIO *bio)
 Retrieves the status whether End-of-File (EOF) has been reached or not, against BIO bio. More...

BIO_METHOD* R_CDECL BIO_s_file ()
 Returns a reference to the static BIO_METHOD used by a file source sink BIO. More...

int R_CDECL BIO_read (BIO *bio, char *out, int outl)
 Reads data through the BIO bio. More...

int R_CDECL BIO_gets (BIO *bio, char *in, int inl)
 Reads a string from the BIO bio into the specified buffer in. More...

int R_CDECL BIO_write (BIO *bio, char *in, int inl)
 Writes data through the BIO bio. More...

int R_CDECL BIO_puts (BIO *bio, char *in)
 Writes the NULL terminated string contained in in to the BIO bio. More...

long R_CDECL BIO_ctrl (BIO *bio, int cmd, long larg, char *parg)
 Provides the replaceable point for all implementation-specific behavior for the I/O. More...

BIO* R_CDECL BIO_push (BIO *bio, BIO *stack)
 Pushes the BIO bio onto the existing BIO stack and returns a pointer to the new stack. More...

BIO* R_CDECL BIO_pop (BIO *bio)
 Pops the uppermost BIO bio from the BIO stack and returns the remaining BIO stack. More...

BIO* R_CDECL BIO_find_type (BIO *bio, int type)
 Returns a BIO from the stack bio with a specified type. More...

BIO* R_CDECL BIO_get_retry_BIO (BIO *bio, int *reason)
 Walks the BIO stack bio and returns the first BIO found that has a retry error set and the reason why the operation should be retried. More...

BIO* R_CDECL BIO_dup_chain (BIO *in)
 Iterates down the BIO stack bio and creates a new copy of each BIO. More...

long MS_CALLBACK R_CDECL BIO_debug_cb (BIO *bio, int cmd, char *argp, int argi, long argl, long ret)
 Sets a prepared callback for the BIO structure bio to output debug information via BIO_set_cb(). More...

BIO_METHOD* R_CDECL BIO_s_mem ()
 Returns a reference to the static BIO_METHOD used by a memory source sink BIO. More...

BIO_METHOD* R_CDECL BIO_s_null ()
 Returns a reference to the static BIO_METHOD used by a NULL source sink BIO. More...

BIO_METHOD* R_CDECL BIO_f_null ()
 Returns a reference to the static BIO_METHOD used by a NULL filter BIO. More...

BIO_METHOD* R_CDECL BIO_f_buffer ()
 Returns a reference to the static BIO_METHOD used by a buffer filter BIO. More...

int R_CDECL BIO_dump (BIO *bio, unsigned char *bytes, int len)
 Dumps the contents of binary data buffer bytes to the BIO structure bio in hexadecimal and ASCII form, removing any trailing spaces or NULL characters. More...

int R_CDECL BIO_dump_format (BIO *bio, unsigned char *data, int len, int format, int separator, int indent, int wrap)
 Specifies the format for dumping the contents of the BIO structure bio. More...

BIO* R_CDECL BIO_new_mem ()
 Creates a memory BIO where all read and write operations refer to an internal memory buffer. More...

BIO* R_CDECL BIO_new_socket (SIO_SOCK fd, int close_flag)
 Creates a socket BIO for a socket file descriptor fd where all read and write operations refer to the socket. More...

BIO* R_CDECL BIO_new_connect (char *host_port)
 Creates a new BIO for use by other BIO functions when connecting to remote machines via TCP. More...

BIO* R_CDECL BIO_new_accept (char *host_port)
 Creates a new accept BIO which listens on the TCP port host_port. More...

void R_CDECL BIO_copy_next_retry (BIO *bio)
 Copies the retry flags and reason from the next BIO in the BIO stack to this BIO bio in order to propagate the retry values up one element in the BIO stack. More...

void R_CDECL BIO_reference_inc (BIO *bio)
 Increments the reference count for the BIO bio. More...

Function Documentation

void R_CDECL BIO_copy_next_retry (  BIO *    bio )  ;
 

Copies the retry flags and reason from the next BIO in the BIO stack to this BIO bio in order to propagate the retry values up one element in the BIO stack.

Parameters:
bio [In, Out] A reference to the BIO to which the flags are copied.

long R_CDECL BIO_ctrl (  BIO *    bio,
int    cmd,
long    larg,
char *    parg
)  ;
 

Provides the replaceable point for all implementation-specific behavior for the I/O. Convenience functions are available to access the functionality provided.

Parameters:
bio [In] A reference to the BIO.
cmd [In] The implementation-specific command.
larg [In] The long argument.
parg [In] The string argument.
Returns:
1 indicates success.
<=0 indicates error.
Samples:
cm_open_strm_cb.c, and cm_vfy_strm_cb.c.

long MS_CALLBACK R_CDECL BIO_debug_cb (  BIO *    bio,
int    cmd,
char *    argp,
int    argi,
long    argl,
long    ret
)  ;
 

Sets a prepared callback for the BIO structure bio to output debug information via BIO_set_cb(). If set, the callback is called for operations including BIO_read() and BIO_write().

The text output of this callback is re-directed to (BIO *) set against the cb_arg field of the BIO. This output BIO is set using BIO_set_cb_arg(). If the cb_arg field is NULL, then stderr may be used if it is available.

Parameters:
bio [In] The BIO reference to write debug information to.
cmd [In] The command code.
A bit field for a function call identifier and return code.
argp [In] The pointer argument.
argi [In] The integer argument.
argl [In] The long argument.
ret [In] The current return code for the BIO function.
Returns:
The return value if BIO_CB_RETURN is set.
1 indicates error.
See also:
BIO_set_cb() and BIO_set_cb_arg().

int BIO_do_accept (  BIO *    bio )  ;
 

Sets up a service side socket that accepts an incoming socket connection on the accept BIO bio. There is no type checking on the BIO when BIO_do_accept() is called. Developers therefore must ensure it is an accept BIO.

After the connection is established, BIO_pop() can be used to retrieve the newly established socket BIO. The first time BIO_do_accept() is called, it performs any required host name lookups and attempts to bind to the socket. Subsequent successful calls to BIO_do_accept() will return when a socket connection has been established.

Parameters:
bio [In, Out] A reference to the BIO.
Returns:
1 indicates success.
<=0 indicates the socket has closed.
-1 indicates an error condition (including retry).
See also:
BIO_new_accept(), BIO_seek() and BIO_pop().
Example:

/* $Id: bio_do_accept.c,v 1.2 2003/05/23 05:20:02 sparki Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved. 
 *
 * This work contains proprietary information of RSA Security. 
 * Distribution is limited to authorized licensees of RSA 
 * Security. Any unauthorized reproduction, distribution or 
 * modification of this work is strictly prohibited.
 */
int ret;

/* listen_bio = BIO_new_accept(...) */

/* hostname lookup, bind to socket and listen */
if ((ret = BIO_do_accept(listen_bio)) <=0)
    {
        /* perform error processing */
        Exit (0);
    }

/* later calls make the remote connection */
while ((ret = BIO_do_accept(listen_bio)) ==1)
    {
        /* handle on new connection */
        new_bio = BIO_pop(listen_bio);

        /* process the connection e.g. using new_bio */
        
        /* close the connection */
        BIO_free(new_bio);
    }
Samples:
bio_server.c, cache_server.c, nbio_server.c, p7ssl_server.c, and ssl_server.c.

int BIO_do_connect (  BIO *    bio )  ;
 

Sets up a client side connection socket on the connect BIO bio.

Parameters:
bio [In, Out] A reference to the BIO.
Returns:
1 indicates success.
<=0 indicates the socket has closed.
-1 indicates non-blocking return if the socket is set as non-blocking.
See also:
BIO_new_accept() and BIO_seek().
Example:

/* $Id: bio_do_connect.c,v 1.2 2003/05/23 05:20:02 sparki Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved. 
 *
 * This work contains proprietary information of RSA Security. 
 * Distribution is limited to authorized licensees of RSA 
 * Security. Any unauthorized reproduction, distribution or 
 * modification of this work is strictly prohibited.
 */
int ret;

/* create new connect BIO */
bio = BIO_new_connect(“www.rsasecurity.com:443”);

ret = BIO_do_connect(bio)

if (ret <=0)
{
    /* perform error processing or non-blocking connection */
}
Samples:
bio_client.c, and nbio_client.c.

int BIO_do_handshake (  BIO *    bio )  ;
 

Attempts to perform the next state in a BIO handshake for BIOs containing state engines.

Parameters:
bio [In, Out] A reference to the BIO.
Returns:
1 indicates success.
<=0 indicates the socket has closed.
-1 indicates possible retry.
Example:

/* $Id: bio_do_handshake.c,v 1.2 2003/05/23 05:20:02 sparki Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved. 
 *
 * This work contains proprietary information of RSA Security. 
 * Distribution is limited to authorized licensees of RSA 
 * Security. Any unauthorized reproduction, distribution or 
 * modification of this work is strictly prohibited.
 */
int ret; 

/* ssl_bio = BIO_new_SSL(...) */ 

/* Complete an SSL handshake */ 
if ((ret = BIO_do_handshake(ssl_bio)) <= 0 ) 
{ 
    /* Deal with an error condition */ 
    exit (0); 
} 

/* Use the connected SSL bio */

int R_CDECL BIO_dump (  BIO *    bio,
unsigned char *    bytes,
int    len
)  ;
 

Dumps the contents of binary data buffer bytes to the BIO structure bio in hexadecimal and ASCII form, removing any trailing spaces or NULL characters. This function is useful for the diagnostic output of binary data buffer contents.

Parameters:
bio [In] The BIO reference to dump the contents to.
bytes [In] The binary data buffer from which to start the dump.
len [In] The amount of data to dump.
Returns:
1 indicates success.
-1 indicates error.
See also:
BIO_dump_format().
Example:

/* $Id: bio_dump.c,v 1.2 2003/05/23 05:20:02 sparki Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved. 
 *
 * This work contains proprietary information of RSA Security. 
 * Distribution is limited to authorized licensees of RSA 
 * Security. Any unauthorized reproduction, distribution or 
 * modification of this work is strictly prohibited.
 */
int len, ret;

/* bio = BIO_new_fp(...) */

/* bytes = find_data_str(...) */

len = strlen(bytes) + 1;
ret = BIO_dump(bio,bytes,len);
if ( ret == -1 )
{
    printf("Failed to output hex dump to BIO\n");
}
Samples:
cm_adv.c, cm_dgst.c, cm_env_strm.c, cm_env_strm_membio.c, cm_open_strm.c, cm_open_strm_cb.c, cm_open_strm_membio.c, cm_sign_strm.c, cm_strm.c, cm_vfy_strm_cb.c, r_asym.c, r_asym_buf.c, r_asym_items.c, r_ciph.c, r_dgst.c, r_gnrt.c, r_hmac.c, r_random.c, and r_sign.c.

int R_CDECL BIO_dump_format (  BIO *    bio,
unsigned char *    data,
int    len,
int    format,
int    separator,
int    indent,
int    wrap
)  ;
 

Specifies the format for dumping the contents of the BIO structure bio. This function is the general purpose hexadecimal dump function.

Parameters:
bio [In] The BIO reference.
data [In] The data to dump.
len [In] The data length.
format [In] The dump format. One of:
  • BIO_DUMP_FORMAT_HEX.
  • BIO_DUMP_FORMAT_HEX_PREFIX.
    • separator [In] The separator character.
    indent [In] The number of characters to indent.
    wrap [In] The number of hexadecimal Bytes to dump per line.
    Returns:
    1 indicates success.
    0 indicates no data to dump.
    -1 indicates error.
    See also:
    BIO_dump().
    Samples:
    cert.c, ext.c, ocsp_req_create.c, ocsp_resp_ext.c, and vfy_adv.c.

    BIO* R_CDECL BIO_dup_chain (  BIO *    in )  ;
     

    Iterates down the BIO stack bio and creates a new copy of each BIO. The copies are pushed onto a duplicate stack.

    Parameters:
    in [In] A reference to the BIO stack to duplicate.
    Returns:
    A reference to the duplicate stack.
    NULL indicates error.
    note.gif
    If BIO_dup_chain() fails, an error is returned and the duplicate stack that was allocated up to that point is freed.
    This is the NULL BIO filter which is used for diagnostic purposes. The filter calls the next BIO in the chain (if one exists) to perform all BIO functionality.
    See also:
    BIO_f_null().

    int BIO_eof (  BIO *    bio )  ;
     

    Retrieves the status whether End-of-File (EOF) has been reached or not, against BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    Returns:
    1 indicates the EOF has been reached.
    -1 indicates error.

    BIO_METHOD* R_CDECL BIO_f_buffer (    )  ;
     

    Returns a reference to the static BIO_METHOD used by a buffer filter BIO. The buffer filter BIO is used to store data where the next BIO in the BIO stack is non-blocking, and may not be able to read or write all requested data within a single call.

    Returns:
    The BIO_METHOD reference for the buffer filter.
    See also:
    BIO_new().

    BIO_METHOD* R_CDECL BIO_f_null (    )  ;
     

    Returns a reference to the static BIO_METHOD used by a NULL filter BIO. A NULL filter BIO does not filter the data read from or written to the next BIO on the BIO stack, but is used to retain the current state of the BIO.

    BIO* R_CDECL BIO_find_type (  BIO *    bio,
    int    type
    )  ;
     

    Returns a BIO from the stack bio with a specified type.

    Parameters:
    bio [In] A reference to the BIO stack to search.
    type [In] The type of BIO to search for in the stack.
    See Type Identifiers for valid values.
    Returns:
    A reference to the desired BIO.
    Otherwise NULL.

    char * BIO_get_accept_port (  BIO *    bio )  ;
     

    Returns the port information for the accept socket of the server.

    Parameters:
    bio [In, Out] A reference to the accept BIO.
    Returns:
    The accept port of the BIO
    NULL indicates otherwise.

    long BIO_get_bind_mode (  BIO *    bio )  ;
     

    Returns the relevant TCP/IP flag for the BIO bio indicating whether a socket can be re-bound. This function is used when restarting the application after a socket shutdown did not execute cleanly. It should only be used for accept BIOs.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    The bind mode. One of:
    Mode Description
    BIO_BIND_NORMAL Indicates no special mode (default).
    BIO_BIND_REUSEADDR Indicates to set the reuse address flag.
    See also:
    BIO_set_bind_mode() and BIO_new_accept().

    int BIO_get_buffer_num_lines (  BIO *    bio )  ;
     

    Returns the number of lines in buffer BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    Returns:
    The number of lines in the buffer.
    -1 indicates error.

    char * BIO_get_conn_hostname (  BIO *    bio )  ;
     

    Returns a pointer to the host name for the connection BIO bio.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    A pointer to the host name.
    NULL indicates error.
    note.gif
    This function only works for a connect BIO or a BIO stack that uses a connect BIO. All other BIO types return NULL.
    See also:
    BIO_set_conn_hostname().
    Example:

    /* $Id: bio_get_conn_hostname.c,v 1.2 2003/05/23 05:20:02 sparki Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved. 
 *
 * This work contains proprietary information of RSA Security. 
 * Distribution is limited to authorized licensees of RSA 
 * Security. Any unauthorized reproduction, distribution or 
 * modification of this work is strictly prohibited.
 */
/* Create a connect BIO */
bio = BIO_new_connect("www.rsa.com:1234");
if ( bio == NULL )
{
    /* Handle the error */
    exit (0);
}

/* Retrieve the host name */
host = BIO_get_conn_hostname(bio);

/* host should point to "www.rsa.com:1234" */

    long BIO_get_conn_int_port (  BIO *    bio,
    int *    portp
    )  ;
     

    Returns the port number for the connection BIO bio.

    Parameters:
    bio [In] A reference to the BIO.
    portp [Out] A pointer to the port value.
    Returns:
    1 indicates success.
    -1 indicates error.
    See also:
    BIO_set_conn_int_port() and BIO_get_conn_port().
    Example:

    /* $Id: bio_get_conn_int_port.c,v 1.3 2005/07/29 01:34:26 build Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved. 
 *
 * This work contains proprietary information of RSA Security. 
 * Distribution is limited to authorized licensees of RSA 
 * Security. Any unauthorized reproduction, distribution or 
 * modification of this work is strictly prohibited.
 */
int port;
BIO * bio;

/* Create a connect BIO */
bio = BIO_new_connect("www.rsa.com");
if ( bio == NULL )
{
    /* Handle the error */
    exit (0);
}

/* Set the port from a string */
BIO_set_conn_port(bio, "1234");

/* Retrieve the port as an integer */
BIO_get_conn_int_port(bio, &port);

/* host should point to 1234 */

    char * BIO_get_conn_ip (  BIO *    bio )  ;
     

    Returns the IP address for the connection BIO bio.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    A pointer to the IP address.
    NULL indicates error.
    See also:
    BIO_set_conn_ip().

    char * BIO_get_conn_port (  BIO *    bio )  ;
     

    Returns the port value for the connection BIO bio as a string.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    A pointer to the port value.
    NULL indicates error.
    See also:
    BIO_set_conn_port().

    long BIO_get_fd (  BIO *    bio,
    char *    fd
    )  ;
     

    Retrieves the read file descriptor fd associated with the BIO bio. The file descriptor is set by a prior call to BIO_set_fd().

    Parameters:
    bio [In] A reference to the BIO.
    fd [Out] A pointer to the file descriptor.
    Returns:
    -1 indicates there was no prior BIO_set_fd() call.
    Otherwise returns the file descriptor associated with the BIO.
    note.gif
    If the address of an integer variable is passed as an argument to BIO_get_fd(), the file descriptor is also assigned to the integer variable. If a NULL address is passed as an argument, it is ignored.
    See also:
    BIO_set_fd().
    Samples:
    bio_client.c, cache_server.c, nbio_client.c, p7ssl_server.c, and ssl_server.c.

    BIO* R_CDECL BIO_get_retry_BIO (  BIO *    bio,
    int *    reason
    )  ;
     

    Walks the BIO stack bio and returns the first BIO found that has a retry error set and the reason why the operation should be retried.

    Parameters:
    bio [In] A reference to the BIO stack.
    reason [Out] The reason code.
    See Retry Reason Identifiers for valid values.
    Returns:
    A reference to the BIO that has a retry error.
    See also:
    BIO_get_retry_flags() and BIO_get_retry_reason().

    long BIO_get_ssl (  BIO *    bio,
    SSL **    sslp
    )  ;
     

    Returns the SSL structure for the SSL BIO bio.

    Parameters:
    bio [In] A reference to the BIO.
    sslp [Out] The address of the SSL reference.
    Returns:
    1 indicates success.
    <=0 indicates error (that is, ssl_ptr is NULL).
    See also:
    BIO_set_ssl_mode.
    Samples:
    bio_client.c, and nbio_client.c.

    int R_CDECL BIO_gets (  BIO *    bio,
    char *    in,
    int    inl
    )  ;
     

    Reads a string from the BIO bio into the specified buffer in. The function is modeled on the standard fgets function.

    Parameters:
    bio [In] A reference to the BIO.
    in [Out] The buffer into which to read the string.
    inl [In] The number of characters to read minus one.
    Returns:
    >0 indicates the number of characters successfully read.
    0 indicates the end of the input.
    <0 indicates error.
    note.gif
    Characters are read until either (inl minus one) characters are completed, or a new line or End-of-File (EOF) is reached.
    See also:
    BIO_puts().
    Samples:
    cm_dgst.c, cm_sign_dgst.c, req.c, and reqgen.c.

    BIO* R_CDECL BIO_new_accept (  char *    host_port )  ;
     

    Creates a new accept BIO which listens on the TCP port host_port. host_port is a text string of the form hostname:port. The listen host for any local interface (that is, the wildcard address) is *.

    Parameters:
    host_port [In] The host and port information.
    Returns:
    The BIO reference.
    note.gif
    To use the accept BIO, call BIO_do_accept(). The first time BIO_new_accept() is called, the socket is created and bound. On the second (and subsequent times) the call only returns when there is an accepted socket. BIO_read() or BIO_write() operations read and write from the BIO until it closes. When the accept BIO has a remote connection, BIO_pop() returns a socket BIO and re-enables the accept BIO to receive incoming connections.
    The accept BIO does not implement the gets method (that is, BIO_gets() will return the error UNSUPPORTED_METHOD).
    See also:
    BIO_new_connect.
    Example:

    /* $Id: bio_new_accept.c,v 1.2 2003/05/23 05:20:02 sparki Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved. 
 *
 * This work contains proprietary information of RSA Security. 
 * Distribution is limited to authorized licensees of RSA 
 * Security. Any unauthorized reproduction, distribution or 
 * modification of this work is strictly prohibited.
 */
/* create an accept BIO */
bio = BIO_new_accept();

/* set the debug cb for debug information */
BIO_set_cb(bio, BIO_debug_cb);

/* create output BIO */
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);

/* set bio_out as cb_arg for printing */
BIO_set_cb_arg(bio, (char *)bio_out);

/* BIO operations will now print debug information */
    Samples:
    bio_server.c, cache_server.c, nbio_server.c, p7ssl_server.c, and ssl_server.c.

    BIO* R_CDECL BIO_new_connect (  char *    host_port )  ;
     

    Creates a new BIO for use by other BIO functions when connecting to remote machines via TCP. host_port is a text string of the form hostname:port. The host name is an IP address and the port name is either a number or an entry in the services table.

    Parameters:
    host_port [In] The host and port information.
    Returns:
    The BIO reference.
    NULL indicates error.
    note.gif
    This function does not establish a connection or perform a DNS lookup until the first BIO_read() or BIO_write() call is issued, or BIO_do_handshake() is called.
    The connect BIO does not implement the gets method (that is, BIO_gets() returns the error UNSUPPORTED_METHOD).
    See also:
    BIO_new_accept.
    Samples:
    p7ssl_client.c, and ssl_client.c.

    BIO* R_CDECL BIO_new_mem (    )  ;
     

    Creates a memory BIO where all read and write operations refer to an internal memory buffer.

    Returns:
    The BIO reference.
    NULL indicates error.
    note.gif
    All methods are implemented for this type of BIO.
    Samples:
    cm_env_strm_membio.c, cm_open_strm_membio.c, and frombuf.c.

    BIO* R_CDECL BIO_new_socket (  SIO_SOCK    fd,
    int    close_flag
    )  ;
     

    Creates a socket BIO for a socket file descriptor fd where all read and write operations refer to the socket.

    Parameters:
    fd [In] The socket file descriptor.
    close_flag [In] The close flag. One of:
  • BIO_CLOSE.
  • BIO_NOCLOSE.
    • Returns:
    The BIO reference.
    NULL indicates error.
    note.gif
    The socket BIO does not implement the gets method (BIO_gets() returns the error UNSUPPORTED_METHOD).
    Example:

    /* $Id: bio_new_socket.c,v 1.2 2003/05/23 05:20:02 sparki Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved. 
 *
 * This work contains proprietary information of RSA Security. 
 * Distribution is limited to authorized licensees of RSA 
 * Security. Any unauthorized reproduction, distribution or 
 * modification of this work is strictly prohibited.
 */
int sock_fd;

/* Create the socket */
if (SIO_connect("www.aus.rsa.com","4444",0,&sockfd) <= 0)
{
    /* Error condition on socket open */
    exit(0);
}

/* Attach the socket to a bio and choose autoclose for sock_fd */
bio = BIO_new_socket(sock_fd,BIO_CLOSE);

/* Use the BIO */

/* Close the BIO and the socket fd (as per the autoclose flag) */
BIO_free(bio);
bio = NULL;
sock_fd = -1;
    Samples:
    sock_server.c.

    BIO* R_CDECL BIO_pop (  BIO *    bio )  ;
     

    Pops the uppermost BIO bio from the BIO stack and returns the remaining BIO stack.

    Parameters:
    bio [In, Out] A reference to the BIO.
    Returns:
    A reference to the new BIO stack.
    NULL indicates error.
    See also:
    BIO_push().
    Example:

    /* $Id: bio_pop.c,v 1.2 2003/05/23 05:20:02 sparki Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved. 
 *
 * This work contains proprietary information of RSA Security. 
 * Distribution is limited to authorized licensees of RSA 
 * Security. Any unauthorized reproduction, distribution or 
 * modification of this work is strictly prohibited.
 */
/* pop a new connection for an accept BIO */
/* setup the socket and check for errors */
BIO_do_accept(abio); 
for (;;)
{
    BIO_do_accept(abio); /* wait for an incoming connection */
    bio = BIO_pop(abio); /* BIO for the new connection */
    
    /* perform BIO operations */
    
    /* release memory */
    BIO_free(bio);
    
    /* process the next connection */
}
    Samples:
    bio_server.c, cache_server.c, nbio_server.c, p7ssl_server.c, and ssl_server.c.

    BIO* R_CDECL BIO_push (  BIO *    bio,
    BIO *    stack
    )  ;
     

    Pushes the BIO bio onto the existing BIO stack and returns a pointer to the new stack.

    Parameters:
    bio [In, Out] A reference to the BIO.
    stack [In, Out] The existing stack of BIOs.
    Returns:
    A reference to the new BIO stack. One of:
  • stack indicates bio is NULL.
  • bio indicates stack is NULL.
    • note.gif
    bio may be a pointer to a stack of filter BIOs rather than a single BIO.
    Only filter BIOs should be pushed onto a stack. Developers should ensure that the first element (or bottom) of the stack is a source/sink BIO via BIO_find_type(). Filter BIOs that exist on the stack modify data written to them before the data is written to the sink BIO, or modify data after a source BIO reads data.
    See also:
    BIO_pop() and BIO_find_type().
    Example:

    /* $Id: bio_push.c,v 1.2 2003/05/23 05:20:02 sparki Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved. 
 *
 * This work contains proprietary information of RSA Security. 
 * Distribution is limited to authorized licensees of RSA 
 * Security. Any unauthorized reproduction, distribution or 
 * modification of this work is strictly prohibited.
 */
BIO  *hash;
BIO  *bss;
BIO  *bio;
char *bytes = "stack test";
int   len;
int   num_bytes;
char  hash_bytes[EVP_MAX_MD_SIZE];
int   hash_len;

len = strlen(bytes) + 1;

/* Create a source/sink BIO */
bss = BIO_new(BIO_s_null());

/* Create a filter BIO */
hash = BIO_new(BIO_f_md());

/* Configure filter BIO */
BIO_set_md(hash, EVP_md5_digest());

/* Add the filter to the stack */
bio = BIO_push(hash, bss);

/* Write data through the message digest BIO */
num_bytes = BIO_write(bio, bytes, len);
if (num_bytes == -1)
{
    /* Error condition */
}

/* get the message digest bytes */
hash_len = BIO_gets(bio, hash_bytes, sizeof(hash_bytes));

/* Do something with the message digest ... */

/* Close all BIO's and free their memory */
BIO_free_all(bio);
    Samples:
    cm_dgst.c, cm_env_strm.c, cm_env_strm_membio.c, cm_open_strm.c, cm_open_strm_cb.c, cm_open_strm_membio.c, cm_sign_dgst.c, cm_sign_strm.c, cm_strm.c, and cm_vfy_strm_cb.c.

    int R_CDECL BIO_puts (  BIO *    bio,
    char *    in
    )  ;
     

    Writes the NULL terminated string contained in in to the BIO bio.

    Parameters:
    bio [In] A reference to the BIO.
    in [In] The buffer containing the NULL terminated string.
    Returns:
    > 0 indicates the number of characters written.
    <= 0 indicates error.
    note.gif
    Unlike the standard I/O puts function, BIO_puts() does not append a new line to the output.
    See also:
    BIO_gets() and BIO_get_retry_reason().

    int R_CDECL BIO_read (  BIO *    bio,
    char *    out,
    int    outl
    )  ;
     

    Reads data through the BIO bio. The amount of data to read is specified in outl.

    Parameters:
    bio [In] A reference to the BIO.
    out [In, Out] The buffer into which to read the data.
    outl [In] The amount of data to read.
    Returns:
    >= 0 indicates the number of Bytes successfully read.
    < 0 indicates error.
    note.gif
    If a non-fatal error occurs, BIO_should_retry() will return a non-zero value and the read should be retried when additional data is available.
    See also:
    BIO_write() and BIO_should_retry().
    Samples:
    bio_client.c, bio_server.c, cm_dgst.c, cm_env_strm.c, cm_env_strm_membio.c, cm_open_strm.c, cm_open_strm_cb.c, cm_open_strm_membio.c, cm_sign_dgst.c, cm_sign_strm.c, cm_strm.c, cm_vfy_strm_cb.c, nbio_client.c, nbio_server.c, r_asym.c, and r_sign.c.

    void R_CDECL BIO_reference_inc (  BIO *    bio )  ;
     

    Increments the reference count for the BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    note.gif
    If BIO_free() is called it checks the reference count of the BIO. If this count is not zero then the memory is not freed because another pointer may be accessing it.
    See also:
    BIO_free().

    int BIO_reset (  BIO *    bio )  ;
     

    Resets the BIO bio to its initial state.

    Parameters:
    bio [In, Out] A reference to the BIO.
    Returns:
    1 indicate success.
    -1 indicates error.
    note.gif
    The initial state of a BIO depends on the type of BIO. For example, file BIOs reset pointers to the start of the file. Connect and accept BIOs reset their state engines. Socket BIOs reset the usage of the socket.
    Samples:
    frombuf.c, r_asym.c, and r_sign.c.

    BIO_METHOD* R_CDECL BIO_s_file (  void    )  ;
     

    Returns a reference to the static BIO_METHOD used by a file source sink BIO. The file source sink BIO is only available on platforms supporting file operations.

    Returns:
    The BIO_METHOD reference for the file.
    See also:
    BIO_new().

    BIO_METHOD* R_CDECL BIO_s_mem (    )  ;
     

    Returns a reference to the static BIO_METHOD used by a memory source sink BIO.

    Returns:
    The BIO_METHOD reference for the memory source sink.
    See also:
    BIO_new().

    BIO_METHOD* R_CDECL BIO_s_null (    )  ;
     

    Returns a reference to the static BIO_METHOD used by a NULL source sink BIO. The NULL source sink BIO is used to discard data rather than output it. A read operation from a NULL source sink BIO does not modify the output buffer supplied.

    Returns:
    A BIO_METHOD reference.
    See also:
    BIO_new().

    long BIO_set_accept_bios (  BIO *    accept_bio,
    BIO *    template_bio
    )  ;
     

    Sets the template BIO template_bio that is automatically duplicated when a successful connection occurs on accept_bio.

    Parameters:
    accept_bio [In, Out] A reference to the accept BIO.
    template_bio [In] A reference to the template BIO.
    Returns:
    1 indicates success.
    <=0 indicates error.
    See also:
    BIO_new_accept() and BIO_do_accept().
    Samples:
    bio_server.c, and nbio_server.c.

    char * BIO_set_accept_port (  BIO *    bio,
    char *    name
    )  ;
     

    Sets the port information for the accept socket of the server.

    Parameters:
    bio [In, Out] A reference to the BIO that will be used to accept connections on the port described by name.
    name [In] A NULL terminated character string representing the port on which to accept connections.
    Returns:
    1 indicates success.
    <=0 indicates error.

    long BIO_set_bind_mode (  BIO *    bio,
    int    mode
    )  ;
     

    Sets the relevant TCP/IP flag allowing a socket to be re-bound. The BIO is bio with a bind mode of mode. This is used when restarting the application after a socket shutdown did not execute cleanly.

    Parameters:
    bio [In, Out] A reference to the BIO.
    mode [In] The bind mode. One of:
    Mode Description
    BIO_BIND_NORMAL Indicates no special mode.
    BIO_BIND_REUSEADDR Indicates to set the reuse address flag.
    Returns:
    1 indicates success.
    <=0 indicates error.
    See also:
    BIO_get_bind_mode().
    Samples:
    cache_server.c, p7ssl_server.c, and ssl_server.c.

    int BIO_set_buffer_read_data (  BIO *    bio,
    char *    buf,
    long    num
    )  ;
     

    Sets the buffer read data for BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    buf [In] The data to set.
    num [In] The length of buf.
    Returns:
    1 indicates success.
    -1 indicates error.

    int BIO_set_buffer_size (  BIO *    bio,
    long    size
    )  ;
     

    Sets the buffer size of BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    size [In] The size of the buffer.
    Returns:
    1 indicates success.
    -1 indicates error.
    Samples:
    cm_env_strm.c, cm_env_strm_membio.c, and cm_sign_strm.c.

    long * BIO_set_conn_hostname (  BIO *    bio,
    char *    name
    )  ;
     

    Sets the host name value name for the connection BIO bio when using a UDP or TCP-based BIO.

    Parameters:
    bio [In, Out] A reference to the BIO.
    name [In] The host name value, with optional port.
    Returns:
    1 indicates success.
    <= 0 indicates error.
    note.gif
    This function is only effective if it is used before the connection is made.
    See also:
    BIO_get_conn_hostname(), BIO_set_conn_ip(), BIO_set_conn_port() and BIO_set_conn_int_port().
    Samples:
    bio_client.c, and nbio_client.c.

    long * BIO_set_conn_int_port (  BIO *    bio,
    int    port
    )  ;
     

    Sets the port value port for the connection BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    port [In] The port value. Must be passed as a variable (not a constant) for this function to compile on Sun platforms.
    Returns:
    1 indicates success.
    <=0 indicates error.
    note.gif
    This function is only effective if it is used before the connection is made.
    See also:
    BIO_get_conn_int_port(), BIO_set_conn_hostname(), BIO_set_conn_ip() and BIO_set_conn_port().

    long * BIO_set_conn_ip (  BIO *    bio,
    char *    ip
    )  ;
     

    Sets the IP address value ip for the connection BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    ip [In] The IP address value.
    Returns:
    1 indicates success.
    <=0 indicates error.
    note.gif
    This function is only effective if it is used before the connection is made.
    See also:
    BIO_get_conn_ip(), BIO_set_conn_hostname(), BIO_set_conn_port() and BIO_set_conn_int_port().

    long * BIO_set_conn_port (  BIO *    bio,
    char *    port
    )  ;
     

    Sets the port value port for the connection BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    port [In] The port value.
    Returns:
    1 indicates success.
    <=0 indicates error.
    note.gif
    This function is only effective if it is used before the connection is made.
    See also:
    BIO_get_conn_port(), BIO_set_conn_hostname(), BIO_set_conn_ip() and BIO_set_conn_int_port().

    long BIO_set_fd (  BIO *    bio,
    int    fd,
    int    close_flag
    )  ;
     

    Sets the read file descriptor fd to be associated with the BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    fd [In] The file descriptor.
    close_flag [In] The close flag.
    See Shutdown Identifiers for valid values.
    Returns:
    <= 0 indicates error.
    See also:
    BIO_get_fd().

    int BIO_set_mem_eof_return (  BIO *    bio,
    long    v
    )  ;
     

    Sets the BIO bio End Of File (EOF) status.

    Parameters:
    bio [In, Out] A reference to the BIO.
    v [In] The EOF status of the BIO.
    Set to 0 when the stream is finished and no more read retries are required.
    Returns:
    1 indicates success.
    Samples:
    cm_open_strm_membio.c.

    long BIO_set_nbio (  BIO *    bio,
    int    nb_flag
    )  ;
     

    Sets the I/O of the underlying connection to blocking or non-blocking BIO bio. This function is only valid for connect BIOs and accept BIOs (those created via BIO_new_accept() or BIO_new_connect()). It is not valid for socket BIOs (those created via BIO_new_socket()). In order to make a normal socket BIO be non-blocking, the socket must be non-blocking before it is attached to a BIO.

    Parameters:
    bio [In, Out] A reference to the BIO.
    nb_flag [In] The blocking flag. One of:
  • 1 sets to non-blocking I/O.
  • 0 sets to blocking I/O.
    • Returns:
    1 indicates success.
    <=0 indicates error.
    See also:
    BIO_new_accept(), BIO_new_connect() and BIO_new_socket().
    Samples:
    nbio_client.c, and nbio_server.c.

    long BIO_set_nbio_accept (  BIO *    accept_bio,
    int    nb_flag
    )  ;
     

    Sets to blocking or non-blocking I/O of the underlying connection BIO bio. This function is only valid for accept BIOs (those created via BIO_new_accept()). It is not valid for socket BIOs or connect BIOs (those created via BIO_new_socket() or BIO_new_connect()).

    Parameters:
    accept_bio [In, Out] A reference to the accept BIO.
    nb_flag [In] The blocking flag. One of:
  • 1 sets to non-blocking I/O.
  • 0 sets to blocking I/O.
    • Returns:
    1 indicates success.
    <=0 indicates error.
    See also:
    BIO_new_accept(), BIO_set_nbio().

    int BIO_set_read_buffer_size (  BIO *    bio,
    long    size
    )  ;
     

    Sets the read buffer size of BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    size [In] The size of the read buffer.
    Returns:
    1 indicates success.
    -1 indicates error.

    long BIO_set_ssl (  BIO *    bio,
    SSL *    ssl,
    int    close_flag
    )  ;
     

    Sets the SSL structure ssl for the BIO bio. The SSL structure previously set for this BIO is freed.

    Parameters:
    bio [In, Out] A reference to the BIO.
    ssl [In] A reference to the SSL connection.
    close_flag [In] If set to BIO_CLOSE the SSL will be freed by the call to BIO_free_all().
    If set to BIO_NOCLOSE the SSL will need to be explicitly freed by the caller.
    See Shutdown Identifiers for valid values.
    Returns:
    1 indicates success.
    <=0 indicates error.
    note.gif
    If the SSL has a read and write BIO, then the read BIO has its count incremented by this function. Call BIO_free_all() to free a BIO that incorporates an SSL in this manner rather than BIO_free().
    See also:
    BIO_set_ssl_mode() and BIO_new_ssl().

    long BIO_set_ssl_mode (  BIO *    bio,
    int    client
    )  ;
     

    Sets the connection state client of the SSL for the BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    client [In] The client flag. One of:
  • 1 indicates client side SSL.
  • 0 indicates server side SSL.
    • Returns:
    1 indicates success.
    <=0 indicates error.
    See also:
    BIO_set_ssl(), BIO_new_ssl(), SSL_set_connect_state() and SSL_set_accept_state().

    int BIO_set_ssl_renegotiate_bytes (  BIO *    bio,
    int    num
    )  ;
     

    Sets the number of Bytes that are sent between renegotiations for the SSL BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    num [In] The number of Bytes.
    Returns:
    1 indicates success.
    <=0 indicates error.
    See also:
    BIO_set_ssl_renegotiate_timeout().

    int BIO_set_ssl_renegotiate_timeout (  BIO *    bio,
    int    seconds
    )  ;
     

    Sets the renegotiation period for the SSL BIO bio. The renegotiation period specifies the elapsed time between renegotiations.

    Parameters:
    bio [In, Out] A reference to the BIO.
    seconds [In] The renegotiation period.
    Returns:
    1 indicates success.
    <=0 indicates error.
    See also:
    BIO_set_ssl_renegotiate_bytes().

    int BIO_set_write_buffer_size (  BIO *    bio,
    long    size
    )  ;
     

    Sets the write buffer size of BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    size [In] The size of the write buffer.
    Returns:
    1 indicates success.
    -1 indicates error.

    int R_CDECL BIO_write (  BIO *    bio,
    char *    in,
    int    inl
    )  ;
     

    Writes data through the BIO bio. The amount of data to write is specified in inl. This function returns the number of Bytes successfully written.

    Parameters:
    bio [In] A reference to the BIO.
    in [In] The buffer from which to write the data.
    inl [In] The length of data to write.
    Returns:
    >= 0 indicates the number of Bytes written.
    < 0 indicates error.
    note.gif
    If a non-fatal error occurs, BIO_should_retry() returns a non-zero value and the write should be retried.
    See also:
    BIO_read() and BIO_should_retry().
    Samples:
    bio_client.c, bio_server.c, cm_env_strm.c, cm_env_strm_membio.c, cm_open_strm.c, cm_open_strm_cb.c, cm_open_strm_membio.c, cm_sign_dgst.c, cm_sign_strm.c, cm_strm.c, cm_vfy_strm_cb.c, nbio_client.c, nbio_server.c, p7ssl_client.c, r_gnrt.c, reqgen.c, and ssl_client.c.

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