BIO_f_ssl(3)
- NetBSD Manual Pages
BIO_f_ssl(3) OpenSSL BIO_f_ssl(3)
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 - SSL BIO
LIBRARY
libcrypto, -lcrypto
SYNOPSIS
#include <openssl/bio.h>
#include <openssl/ssl.h>
BIO_METHOD *BIO_f_ssl(void);
#define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl)
#define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp)
#define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL)
#define BIO_set_ssl_renegotiate_bytes(b,num) \
BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL);
#define BIO_set_ssl_renegotiate_timeout(b,seconds) \
BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL);
#define BIO_get_num_renegotiates(b) \
BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL);
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);
#define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)
DESCRIPTION
BIO_f_ssl() returns the SSL BIO method. This is a filter
BIO which is a wrapper round the OpenSSL SSL routines
adding a BIO "flavour" to SSL I/O.
I/O performed on an SSL BIO communicates using the SSL
protocol with the SSLs read and write BIOs. If an SSL con-
nection 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() it is
automatically used as the SSL BIOs read and write BIOs.
Calling BIO_reset() on an SSL BIO closes down any current
SSL connection by calling SSL_shutdown(). BIO_reset() is
then sent to the next BIO in the chain: this will typi-
cally disconnect the underlying transport. The SSL BIO is
then reset to the initial accept or connect state.
2001-04-12 0.9.6g 1
BIO_f_ssl(3) OpenSSL BIO_f_ssl(3)
If the close flag is set when an SSL BIO is freed then the
internal SSL structure is also freed using SSL_free().
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 func-
tions.
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 non zero.
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 con-
sisting 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
BIOs in each chain and calling SSL_copy_session_id() 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() 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()
should be used for non blocking connect BIOs to determine
if the call should be retried. If an SSL connection has
already been established this call has no effect.
2001-04-12 0.9.6g 2
BIO_f_ssl(3) OpenSSL BIO_f_ssl(3)
NOTES
SSL BIOs are exceptional in that if the underlying trans-
port 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()
operation, one case where this happens is when SGC or step
up occurs.
In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can
be set to disable this behaviour. That is when this flag
is set an SSL BIO using a blocking transport will never
request a retry.
Since unknown BIO_ctrl() operations are sent through fil-
ter BIOs the servers name and port can be set using
BIO_set_host() on the BIO returned by BIO_new_ssl_con-
nect() 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.
RETURN VALUES
TBA
EXAMPLE
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);
2001-04-12 0.9.6g 3
BIO_f_ssl(3) OpenSSL BIO_f_ssl(3)
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 buffer-
ing BIO to allow lines to be read from the SSL BIO using
BIO_gets. 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;
ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();
/* Might seed PRNG here */
2001-04-12 0.9.6g 4
BIO_f_ssl(3) OpenSSL BIO_f_ssl(3)
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);
/* Setup accept BIO */
if(BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error setting up accept BIO\n");
ERR_print_errors_fp(stderr);
return 0;
}
2001-04-12 0.9.6g 5
BIO_f_ssl(3) OpenSSL BIO_f_ssl(3)
/* Now wait for incoming connection */
if(BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error in connection\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/html\r\n\r\n");
BIO_puts(sbio, "<pre>\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, "</pre>\r\n");
/* Since there is a buffering BIO present we had better flush it */
BIO_flush(sbio);
BIO_free_all(sbio);
SEE ALSO
TBA
2001-04-12 0.9.6g 6
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.