1 files changed, 475 insertions, 0 deletions

diff --git a/src/lib/libssl/doc/BIO_f_ssl.3 b/src/lib/libssl/doc/BIO_f_ssl.3
new file mode 100644
index 0000000000..31c9963edb
--- /dev/null
+++ b/src/lib/libssl/doc/BIO_f_ssl.3
@@ -0,0 +1,475 @@
+.Dd $Mdocdate: October 12 2014 $
+.Dt BIO_F_SSL 3
+.Os
+.Sh NAME
+.Nm BIO_f_ssl ,
+.Nm BIO_set_ssl ,
+.Nm BIO_get_ssl ,
+.Nm BIO_set_ssl_mode ,
+.Nm BIO_set_ssl_renegotiate_bytes ,
+.Nm BIO_get_num_renegotiates ,
+.Nm BIO_set_ssl_renegotiate_timeout ,
+.Nm BIO_new_ssl ,
+.Nm BIO_new_ssl_connect ,
+.Nm BIO_new_buffer_ssl_connect ,
+.Nm BIO_ssl_copy_session_id ,
+.Nm BIO_ssl_shutdown
+.Nd SSL BIO
+.Sh SYNOPSIS
+.In openssl/bio.h
+.In openssl/ssl.h
+.Ft BIO_METHOD *
+.Fn BIO_f_ssl void
+.Fd #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl)
+.Fd #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp)
+.Fd #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL)
+.Fd #define BIO_set_ssl_renegotiate_bytes(b,num) \
+BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL)
+.Fd #define BIO_set_ssl_renegotiate_timeout(b,seconds) \
+BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL)
+.Fd #define BIO_get_num_renegotiates(b) \
+BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL)
+.Ft BIO *
+.Fn BIO_new_ssl "SSL_CTX *ctx" "int client"
+.Ft BIO *
+.Fn BIO_new_ssl_connect "SSL_CTX *ctx"
+.Ft BIO *
+.Fn BIO_new_buffer_ssl_connect "SSL_CTX *ctx"
+.Ft int
+.Fn BIO_ssl_copy_session_id "BIO *to" "BIO *from"
+.Ft void
+.Fn BIO_ssl_shutdown "BIO *bio"
+.Fd #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)
+.Sh DESCRIPTION
+.Fn BIO_f_ssl
+returns the
+.Vt SSL
+.Vt BIO
+method.
+This is a filter
+.Vt BIO
+which is a wrapper around the OpenSSL
+.Vt SSL
+routines adding a
+.Vt BIO
+.Dq flavor
+to SSL I/O.
+.Pp
+I/O performed on an
+.Vt SSL
+.Vt BIO
+communicates using the SSL protocol with
+the
+.Vt SSL Ns 's
+read and write
+.Vt BIO Ns s.
+If an SSL connection is not established then an attempt is made to establish
+one on the first I/O call.
+.Pp
+If a
+.Vt BIO
+is appended to an
+.Vt SSL
+.Vt BIO
+using
+.Xr BIO_push 3
+it is automatically used as the
+.Vt SSL
+.Vt BIO Ns 's read and write
+.Vt BIO Ns s.
+.Pp
+Calling
+.Xr BIO_reset 3
+on an
+.Vt SSL
+.Vt BIO
+closes down any current SSL connection by calling
+.Xr SSL_shutdown 3 .
+.Xr BIO_reset
+is then sent to the next
+.Vt BIO
+in the chain; this will typically disconnect the underlying transport.
+The
+.Vt SSL
+.Vt BIO
+is then reset to the initial accept or connect state.
+.Pp
+If the close flag is set when an
+.Vt SSL
+.Vt BIO
+is freed then the internal
+.Vt SSL
+structure is also freed using
+.Xr SSL_free 3 .
+.Pp
+.Fn BIO_set_ssl
+sets the internal
+.Vt SSL
+pointer of
+.Vt BIO
+.Fa b
+to
+.Fa ssl
+using
+the close flag
+.Fa c .
+.Pp
+.Fn BIO_get_ssl
+retrieves the
+.Vt SSL
+pointer of
+.Vt BIO
+.Fa b ;
+it can then be manipulated using the standard SSL library functions.
+.Pp
+.Fn BIO_set_ssl_mode
+sets the
+.Vt SSL
+.Vt BIO
+mode to
+.Fa client .
+If
+.Fa client
+is 1, client mode is set.
+If
+.Fa client
+is 0, server mode is set.
+.Pp
+.Fn BIO_set_ssl_renegotiate_bytes
+sets the renegotiate byte count to
+.Fa num .
+When set after every
+.Fa num
+bytes of I/O (read and write) the SSL session is automatically renegotiated.
+.Fa num
+must be at least 512 bytes.
+.Pp
+.Fn BIO_set_ssl_renegotiate_timeout
+sets the renegotiate timeout to
+.Fa seconds .
+When the renegotiate timeout elapses the session is automatically renegotiated.
+.Pp
+.Fn BIO_get_num_renegotiates
+returns the total number of session renegotiations due to I/O or timeout.
+.Pp
+.Fn BIO_new_ssl
+allocates an
+.Vt SSL
+.Vt BIO
+using
+.Vt SSL_CTX
+.Va ctx
+and using client mode if
+.Fa client
+is nonzero.
+.Pp
+.Fn BIO_new_ssl_connect
+creates a new
+.Vt BIO
+chain consisting of an
+.Vt SSL
+.Vt BIO
+(using
+.Fa ctx )
+followed by a connect BIO.
+.Pp
+.Fn BIO_new_buffer_ssl_connect
+creates a new
+.Vt BIO
+chain consisting of a buffering
+.Vt BIO ,
+an
+.Vt SSL
+.Vt BIO
+(using
+.Fa ctx )
+and a connect
+.Vt BIO .
+.Pp
+.Fn BIO_ssl_copy_session_id
+copies an SSL session id between
+.Vt BIO
+chains
+.Fa from
+and
+.Fa to .
+It does this by locating the
+.Vt SSL
+.Vt BIO Ns s
+in each chain and calling
+.Xr SSL_copy_session_id 3
+on the internal
+.Vt SSL
+pointer.
+.Pp
+.Fn BIO_ssl_shutdown
+closes down an SSL connection on
+.Vt BIO
+chain
+.Fa bio .
+It does this by locating the
+.Vt SSL
+.Vt BIO
+in the
+chain and calling
+.Xr SSL_shutdown 3
+on its internal
+.Vt SSL
+pointer.
+.Pp
+.Fn BIO_do_handshake
+attempts to complete an SSL handshake on the supplied
+.Vt 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
+.Xr BIO_should_retry 3
+should be used for non blocking connect
+.Vt BIO Ns s
+to determine if the call should be retried.
+If an SSL connection has already been established this call has no effect.
+.Sh NOTES
+.Vt SSL
+.Vt BIO Ns 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
+.Xr BIO_read 3
+operation.
+One case where this happens is when SGC or step up occurs.
+.Pp
+In OpenSSL 0.9.6 and later the SSL flag
+.Dv SSL_AUTO_RETRY
+can be set to disable this behaviour.
+In other words, when this flag is set an
+.Vt SSL
+.Vt BIO
+using a blocking transport will never request a retry.
+.Pp
+Since unknown
+.Xr BIO_ctrl 3
+operations are sent through filter
+.Vt BIO Ns s
+the server name and port can be set using
+.Xr BIO_set_host 3
+on the
+.Vt BIO
+returned by
+.Fn BIO_new_ssl_connect
+without having to locate the connect
+.Vt BIO
+first.
+.Pp
+Applications do not have to call
+.Fn BIO_do_handshake
+but may wish to do so to separate the handshake process from other I/O
+processing.
+.Sh RETURN VALUES
+.\" XXX
+This section is incomplete.
+.Sh 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
+.Xr BIO_s_connect 3 .
+.Bd -literal
+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\en");
+        /* 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\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);
+.Ed
+.Pp
+Here is a simple server example.
+It makes use of a buffering
+.Vt BIO
+to allow lines to be read from the
+.Vt SSL
+.Vt BIO
+using
+.Xr BIO_gets 3 .
+It creates a pseudo web page containing the actual request from a client and
+also echoes the request to standard output.
+.Bd -literal
+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't locate SSL pointer\en");
+        /* 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\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] == '\er') || (tmpbuf[0] == '\en'))
+                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);
+.Ed
+.Sh BUGS
+In OpenSSL versions before 1.0.0 the
+.Xr BIO_pop 3
+call was handled incorrectly:
+the I/O BIO reference count was incorrectly incremented (instead of
+decremented) and dissociated with the
+.Vt SSL
+.Vt BIO
+even if the
+.Vt SSL
+.Vt BIO
+was not
+explicitly being popped (e.g., a pop higher up the chain).
+Applications which included workarounds for this bug (e.g., freeing BIOs more
+than once) should be modified to handle this fix or they may free up an already
+freed
+.Vt BIO .