Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is turned on, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF
Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "BIO_f_ssl 3"
way too many mistakes in technical documents.
I/O performed on an \s-1SSL BIO\s0 communicates using the \s-1SSL\s0 protocol with the SSLs read and write BIOs. If an \s-1SSL\s0 connection is not established then an attempt is made to establish one on the first I/O call.
If a \s-1BIO\s0 is appended to an \s-1SSL BIO\s0 using BIO_push() it is automatically used as the \s-1SSL\s0 BIOs read and write BIOs.
Calling BIO_reset() on an \s-1SSL BIO\s0 closes down any current \s-1SSL\s0 connection by calling SSL_shutdown(). BIO_reset() is then sent to the next \s-1BIO\s0 in the chain: this will typically disconnect the underlying transport. The \s-1SSL BIO\s0 is then reset to the initial accept or connect state.
If the close flag is set when an \s-1SSL BIO\s0 is freed then the internal \s-1SSL\s0 structure is also freed using SSL_free().
\fIBIO_set_ssl() sets the internal \s-1SSL\s0 pointer of \s-1BIO \s0b to ssl using the close flag c.
\fIBIO_get_ssl() retrieves the \s-1SSL\s0 pointer of \s-1BIO \s0b, it can then be manipulated using the standard \s-1SSL\s0 library functions.
\fIBIO_set_ssl_mode() sets the \s-1SSL BIO\s0 mode to client. If client is 1 client mode is set. If client is 0 server mode is set.
\fIBIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count to num. When set after every num bytes of I/O (read and write) the \s-1SSL\s0 session is automatically renegotiated. num must be at least 512 bytes.
\fIBIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to \fBseconds. When the renegotiate timeout elapses the session is automatically renegotiated.
\fIBIO_get_num_renegotiates() returns the total number of session renegotiations due to I/O or timeout.
\fIBIO_new_ssl() allocates an \s-1SSL BIO\s0 using \s-1SSL_CTX \s0ctx and using client mode if client is non zero.
\fIBIO_new_ssl_connect() creates a new \s-1BIO\s0 chain consisting of an \s-1SSL BIO \s0(using ctx) followed by a connect \s-1BIO.\s0
\fIBIO_new_buffer_ssl_connect() creates a new \s-1BIO\s0 chain consisting of a buffering \s-1BIO,\s0 an \s-1SSL BIO \s0(using ctx) and a connect \s-1BIO.\s0
\fIBIO_ssl_copy_session_id() copies an \s-1SSL\s0 session id between \s-1BIO\s0 chains from and to. It does this by locating the \s-1SSL\s0 BIOs in each chain and calling SSL_copy_session_id() on the internal \s-1SSL\s0 pointer.
\fIBIO_ssl_shutdown() closes down an \s-1SSL\s0 connection on \s-1BIO\s0 chain bio. It does this by locating the \s-1SSL BIO\s0 in the chain and calling SSL_shutdown() on its internal \s-1SSL\s0 pointer.
\fIBIO_do_handshake() attempts to complete an \s-1SSL\s0 handshake on the supplied \s-1BIO\s0 and establish the \s-1SSL\s0 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 \s-1SSL\s0 connection has already been established this call has no effect.
In OpenSSL 0.9.6 and later the \s-1SSL\s0 flag \s-1SSL_AUTO_RETRY\s0 can be set to disable this behaviour. That is when this flag is set an \s-1SSL BIO\s0 using a blocking transport will never request a retry.
Since unknown BIO_ctrl() operations are sent through filter BIOs the servers name and port can be set using BIO_set_host() on the \s-1BIO\s0 returned by BIO_new_ssl_connect() without having to locate the connect \s-1BIO\s0 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.
.Vb 5 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\*(Aqt * do it automatically */ \& ctx = SSL_CTX_new(SSLv23_client_method()); \& /* We\*(Aqd 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\*(Aqt locate SSL pointer\en"); /* whatever ... */ } \& /* Don\*(Aqt 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\en"); ERR_print_errors_fp(stderr); /* whatever ... */ } \& if(BIO_do_handshake(sbio) <= 0) { fprintf(stderr, "Error establishing SSL connection\en"); ERR_print_errors_fp(stderr); /* whatever ... */ } \& /* Could examine ssl here to get connection info */ \& BIO_puts(sbio, "GET / HTTP/1.0\en\en"); for(;;) { len = BIO_read(sbio, tmpbuf, 1024); if(len <= 0) break; BIO_write(out, tmpbuf, len); } BIO_free_all(sbio); BIO_free(out); .Ve
Here is a simple server example. It makes use of a buffering \s-1BIO\s0 to allow lines to be read from the \s-1SSL BIO\s0 using BIO_gets. It creates a pseudo web page containing the actual request from a client and also echoes the request to standard output.
.Vb 5 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 */ \& 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\en"); 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\*(Aqt locate SSL pointer\en"); /* whatever ... */ } \& /* Don\*(Aqt 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 \*(Aqswallowed\*(Aq 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\en"); ERR_print_errors_fp(stderr); return 0; } \& /* Now wait for incoming connection */ if(BIO_do_accept(acpt) <= 0) { fprintf(stderr, "Error in connection\en"); 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\en"); ERR_print_errors_fp(stderr); return 0; } \& BIO_puts(sbio, "HTTP/1.0 200 OK\er\enContent-type: text/plain\er\en\er\en"); BIO_puts(sbio, "\er\enConnection Established\er\enRequest headers:\er\en"); BIO_puts(sbio, "--------------------------------------------------\er\en"); \& 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] == \*(Aq\er\*(Aq) || (tmpbuf[0] == \*(Aq\en\*(Aq)) break; } \& BIO_puts(sbio, "--------------------------------------------------\er\en"); BIO_puts(sbio, "\er\en"); \& /* Since there is a buffering BIO present we had better flush it */ BIO_flush(sbio); \& BIO_free_all(sbio); .Ve