---
name: "libressl-BIO_f_ssl"
section: "3"
platform: "linux"
package: "libressl"
version: "4.4.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libressl-BIO_f_ssl"
---

# libressl-BIO\_f\_ssl(3)

SSL BIO

## NAME

**BIO\_f\_ssl**, **BIO\_set\_ssl**, **BIO\_get\_ssl**, **BIO\_set\_ssl\_mode**, **BIO\_set\_ssl\_renegotiate\_bytes**, **BIO\_get\_num\_renegotiates**, **BIO\_set\_ssl\_renegotiate\_timeout**, **BIO\_new\_ssl**, **BIO\_new\_ssl\_connect**, **BIO\_new\_buffer\_ssl\_connect**, **BIO\_ssl\_copy\_session\_id**, **BIO\_ssl\_shutdown**, **BIO\_do\_handshake** – SSL BIO

## SYNOPSIS

SSL Library (libssl, -lssl) libcrypto

**#include \<openssl/bio.h\>**

**#include \<openssl/ssl.h\>**

*const* *BIO\_METHOD* *\**\

**BIO\_f\_ssl**(*void*);

*long*\

**BIO\_set\_ssl**(*BIO \*b*, *SSL \*ssl*, *long c*);

*long*\

**BIO\_get\_ssl**(*BIO \*b*, *SSL \*sslp*);

*long*\

**BIO\_set\_ssl\_mode**(*BIO \*b*, *long client*);

*long*\

**BIO\_set\_ssl\_renegotiate\_bytes**(*BIO \*b*, *long num*);

*long*\

**BIO\_set\_ssl\_renegotiate\_timeout**(*BIO \*b*, *long seconds*);

*long*\

**BIO\_get\_num\_renegotiates**(*BIO \*b*);

*BIO* *\**\

**BIO\_new\_ssl**(*SSL\_CTX \*ctx*, *int client*);

*BIO* *\**\

**BIO\_new\_ssl\_connect**(*SSL\_CTX \*ctx*);

*BIO* *\**\

**BIO\_new\_buffer\_ssl\_connect**(*SSL\_CTX \*ctx*);

*int*\

**BIO\_ssl\_copy\_session\_id**(*BIO \*to*, *BIO \*from*);

*void*\

**BIO\_ssl\_shutdown**(*BIO \*bio*);

*long*\

**BIO\_do\_handshake**(*BIO \*b*);

## DESCRIPTION

**BIO\_f\_ssl**() returns the *SSL* *BIO* method. This is a filter *BIO* which is a wrapper around the OpenSSL *SSL* routines adding a *BIO* “flavor” to SSL I/O.

I/O performed on an *SSL* *BIO* communicates using the SSL protocol with the *SSL*'s read and write *BIO*s. If an SSL connection is not established then an attempt is made to establish one on the first I/O call.

If a *BIO* is appended to an *SSL* *BIO* using BIO\_push(3), it is automatically used as the *SSL* *BIO*'s read and write *BIO*s.

Calling BIO\_reset(3) on an *SSL* *BIO* closes down any current SSL connection by calling SSL\_shutdown(3). BIO\_reset(3) is then sent to the next *BIO* in the chain; this will typically disconnect the underlying transport. The *SSL* *BIO* is then reset to the initial accept or connect state.

If the close flag is set when an *SSL* *BIO* is freed then the internal *SSL* structure is also freed using SSL\_free(3).

**BIO\_set\_ssl**() sets the internal *SSL* pointer of *BIO* *b* to *ssl* using the close flag *c*.

**BIO\_get\_ssl**() retrieves the *SSL* pointer of *BIO* *b*; it can then be manipulated using the standard SSL library functions.

**BIO\_set\_ssl\_mode**() sets the *SSL* *BIO* mode to *client*. If *client* is 1, client mode is set. If *client* is 0, server mode is set.

**BIO\_set\_ssl\_renegotiate\_bytes**() sets the renegotiate byte count to *num*. When set, after every *num* bytes of I/O (read and write) the SSL session is automatically renegotiated. *num* must be at least 512 bytes.

**BIO\_set\_ssl\_renegotiate\_timeout**() sets the renegotiate timeout to *seconds*. When the renegotiate timeout elapses, the session is automatically renegotiated.

**BIO\_get\_num\_renegotiates**() returns the total number of session renegotiations due to I/O or timeout.

**BIO\_new\_ssl**() allocates an *SSL* *BIO* using *SSL\_CTX* *ctx* and using client mode if *client* is nonzero.

**BIO\_new\_ssl\_connect**() creates a new *BIO* chain consisting of an *SSL* *BIO* (using *ctx*) followed by a connect BIO.

**BIO\_new\_buffer\_ssl\_connect**() creates a new *BIO* chain consisting of a buffering *BIO*, an *SSL* *BIO* (using *ctx*) and a connect *BIO*.

**BIO\_ssl\_copy\_session\_id**() copies an SSL session id between *BIO* chains *from* and *to*. It does this by locating the *SSL* *BIO*s in each chain and calling SSL\_copy\_session\_id(3) on the internal *SSL* pointer.

**BIO\_ssl\_shutdown**() closes down an SSL connection on *BIO* chain *bio*. It does this by locating the *SSL* *BIO* in the chain and calling SSL\_shutdown(3) on its internal *SSL* pointer.

**BIO\_do\_handshake**() attempts to complete an SSL handshake on the supplied *BIO* and establish the SSL connection. It returns 1 if the connection was established successfully. A zero or negative value is returned if the connection could not be established; the call BIO\_should\_retry(3) should be used for non blocking connect *BIO*s to determine if the call should be retried. If an SSL connection has already been established, this call has no effect.

When a chain containing an SSL BIO is copied with BIO\_dup\_chain(3), SSL\_dup(3) is called internally to copy the *SSL* object from the existing BIO object to the new BIO object, and the internal data related to **BIO\_set\_ssl\_renegotiate\_bytes**() and **BIO\_set\_ssl\_renegotiate\_timeout**() is also copied.

*SSL* *BIO*s are exceptional in that if the underlying transport is non-blocking they can still request a retry in exceptional circumstances. Specifically this will happen if a session renegotiation takes place during a BIO\_read(3) operation. One case where this happens is when step up occurs.

In OpenSSL 0.9.6 and later the SSL flag SSL\_AUTO\_RETRY can be set to disable this behaviour. In other words, when this flag is set an *SSL* *BIO* using a blocking transport will never request a retry.

Since unknown BIO\_ctrl(3) operations are sent through filter *BIO*s, the server name and port can be set using BIO\_set\_conn\_hostname(3) and BIO\_set\_conn\_port(3) on the *BIO* returned by **BIO\_new\_ssl\_connect**() without having to locate the connect *BIO* first.

Applications do not have to call **BIO\_do\_handshake**() but may wish to do so to separate the handshake process from other I/O processing.

**BIO\_set\_ssl**(), **BIO\_get\_ssl**(), **BIO\_set\_ssl\_mode**(), **BIO\_set\_ssl\_renegotiate\_bytes**(), **BIO\_set\_ssl\_renegotiate\_timeout**(), **BIO\_get\_num\_renegotiates**(), and **BIO\_do\_handshake**() are implemented as macros.

## RETURN VALUES

**BIO\_f\_ssl**() returns a pointer to a static *BIO\_METHOD* structure.

When called on an SSL BIO object, BIO\_method\_type(3) returns the constant BIO\_TYPE\_SSL and BIO\_method\_name(3) returns a pointer to the static string "ssl".

**BIO\_set\_ssl**(), **BIO\_get\_ssl**(), **BIO\_set\_ssl\_mode**(), **BIO\_set\_ssl\_renegotiate\_bytes**(), **BIO\_set\_ssl\_renegotiate\_timeout**(), and **BIO\_get\_num\_renegotiates**() return 1 on success or a value less than or equal to 0 if an error occurred.

**BIO\_new\_ssl**(), **BIO\_new\_ssl\_connect**(), and **BIO\_new\_buffer\_ssl\_connect**() returns a pointer to a newly allocated *BIO* chain or NULL if an error occurred.

**BIO\_ssl\_copy\_session\_id**() returns 1 on success or 0 on error.

**BIO\_do\_handshake**() returns 1 if the connection was established successfully or a value less than or equal to 0 otherwise.

## EXAMPLES

This SSL/TLS client example attempts to retrieve a page from an SSL/TLS web server. The I/O routines are identical to those of the unencrypted example in BIO\_s\_connect(3).

```
BIO *sbio, *out;
int len;
char tmpbuf[1024];
SSL_CTX *ctx;
SSL *ssl;
ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();
/*
 * We would seed the PRNG here if the platform didn't do it automatically
 */
ctx = SSL_CTX_new(SSLv23_client_method());
/*
 * We'd normally set some stuff like the verify paths and mode here because
 * as things stand this will connect to any server whose certificate is
 * signed by any CA.
 */
sbio = BIO_new_ssl_connect(ctx);
BIO_get_ssl(sbio, &ssl);
if (!ssl) {
	fprintf(stderr, "Can't locate SSL pointer\n");
	/* whatever ... */
}
/* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
/* We might want to do other things with ssl here */
BIO_set_conn_hostname(sbio, "localhost:https");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if (BIO_do_connect(sbio) <= 0) {
	fprintf(stderr, "Error connecting to server\n");
	ERR_print_errors_fp(stderr);
	/* whatever ... */
}
if (BIO_do_handshake(sbio) <= 0) {
	fprintf(stderr, "Error establishing SSL connection\n");
	ERR_print_errors_fp(stderr);
	/* whatever ... */
}
/* Could examine ssl here to get connection info */
BIO_puts(sbio, "GET / HTTP/1.0\n\n");
for (;;) {
	len = BIO_read(sbio, tmpbuf, 1024);
	if(len <= 0) break;
	BIO_write(out, tmpbuf, len);
}
BIO_free_all(sbio);
BIO_free(out);
```

Here is a simple server example. It makes use of a buffering *BIO* to allow lines to be read from the *SSL* *BIO* using BIO\_gets(3). It creates a pseudo web page containing the actual request from a client and also echoes the request to standard output.

```
BIO *sbio, *bbio, *acpt, *out;
int len;
char tmpbuf[1024];
SSL_CTX *ctx;
SSL *ssl;
ctx = SSL_CTX_new(SSLv23_server_method());
if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM)
    || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM)
    || !SSL_CTX_check_private_key(ctx)) {
	fprintf(stderr, "Error setting up SSL_CTX\n");
	ERR_print_errors_fp(stderr);
	return 0;
}
/*
 * Might do other things here like setting verify locations and DH and/or
 * RSA temporary key callbacks
 */
/* New SSL BIO setup as server */
sbio = BIO_new_ssl(ctx,0);
BIO_get_ssl(sbio, &ssl);
if (!ssl) {
	fprintf(stderr, "Can't locate SSL pointer\n");
	/* whatever ... */
}
/* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
/* Create the buffering BIO */
bbio = BIO_new(BIO_f_buffer());
/* Add to chain */
sbio = BIO_push(bbio, sbio);
acpt = BIO_new_accept("4433");
/*
 * By doing this when a new connection is established we automatically
 * have sbio inserted into it. The BIO chain is now 'swallowed' by the
 * accept BIO and will be freed when the accept BIO is freed.
 */
BIO_set_accept_bios(acpt,sbio);
out = BIO_new_fp(stdout, BIO_NOCLOSE);
/* Wait for incoming connection */
if (BIO_do_accept(acpt) <= 0) {
	fprintf(stderr, "Error setting up accept BIO\n");
	ERR_print_errors_fp(stderr);
	return 0;
}
/* We only want one connection so remove and free accept BIO */
sbio = BIO_pop(acpt);
BIO_free_all(acpt);
if (BIO_do_handshake(sbio) <= 0) {
	fprintf(stderr, "Error in SSL handshake\n");
	ERR_print_errors_fp(stderr);
	return 0;
}
BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
BIO_puts(sbio, "--------------------------------------------------\r\n");
for (;;) {
	len = BIO_gets(sbio, tmpbuf, 1024);
	if (len <= 0)
		break;
	BIO_write(sbio, tmpbuf, len);
	BIO_write(out, tmpbuf, len);
	/* Look for blank line signifying end of headers */
	if ((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n'))
		break;
}
BIO_puts(sbio, "--------------------------------------------------\r\n");
BIO_puts(sbio, "\r\n");
/* Since there is a buffering BIO present we had better flush it */
BIO_flush(sbio);
BIO_free_all(sbio);
```

## SEE ALSO

BIO\_new(3), [ssl(3)](/ssl/3.md)

## HISTORY

**BIO\_f\_ssl**(), **BIO\_set\_ssl**(), and **BIO\_get\_ssl**() first appeared in SSLeay 0.6.0. **BIO\_set\_ssl\_mode**(), **BIO\_new\_ssl**(), and **BIO\_ssl\_copy\_session\_id**() first appeared in SSLeay 0.8.0. **BIO\_ssl\_shutdown**() and **BIO\_do\_handshake**() first appeared in SSLeay 0.8.1. **BIO\_set\_ssl\_renegotiate\_bytes**(), **BIO\_get\_num\_renegotiates**(), **BIO\_set\_ssl\_renegotiate\_timeout**(), **BIO\_new\_ssl\_connect**(), and **BIO\_new\_buffer\_ssl\_connect**() first appeared in SSLeay 0.9.0. All these functions have been available since OpenBSD 2.4.