Update build for OpenSSL-0.9.8j upgrade.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_f_ssl.3
index 66d97c4..9d8667b 100644 (file)
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
 .\"
 .\" 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.  | will give a
-.\" real vertical bar.  \*(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-|\(bv\*(Tr
+.\" 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 C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 .ie n \{\
 .    ds -- \(*W-
 .    ds R" ''
 'br\}
 .\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
 .\" If the F register is turned on, we'll generate index entries on stderr for
 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
-.if \nF \{\
+.ie \nF \{\
 .    de IX
 .    tm Index:\\$1\t\\n%\t"\\$2"
 ..
 .    nr % 0
 .    rr F
 .\}
-.\"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.el \{\
+.    de IX
+..
+.\}
 .\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
 .\" ========================================================================
 .\"
 .IX Title "BIO_f_ssl 3"
-.TH BIO_f_ssl 3 "2008-09-27" "0.9.8i" "OpenSSL"
+.TH BIO_f_ssl 3 "2009-01-11" "0.9.8j" "OpenSSL"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
 .SH "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,
@@ -140,13 +147,9 @@ BIO_ssl_shutdown \- SSL BIO
 .Vb 2
 \& #include <openssl/bio.h>
 \& #include <openssl/ssl.h>
-.Ve
-.PP
-.Vb 1
+\&
 \& BIO_METHOD *BIO_f_ssl(void);
-.Ve
-.PP
-.Vb 9
+\&
 \& #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)
@@ -156,24 +159,20 @@ BIO_ssl_shutdown \- SSL BIO
 \&        BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL);
 \& #define BIO_get_num_renegotiates(b) \e
 \&        BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL);
-.Ve
-.PP
-.Vb 5
+\&
 \& 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);
-.Ve
-.PP
-.Vb 1
+\&
 \& #define BIO_do_handshake(b)    BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)
 .Ve
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 \&\fIBIO_f_ssl()\fR returns the \s-1SSL\s0 \s-1BIO\s0 method. This is a filter \s-1BIO\s0 which
 is a wrapper round the OpenSSL \s-1SSL\s0 routines adding a \s-1BIO\s0 \*(L"flavour\*(R" to
-\&\s-1SSL\s0 I/O. 
+\&\s-1SSL\s0 I/O.
 .PP
 I/O performed on an \s-1SSL\s0 \s-1BIO\s0 communicates using the \s-1SSL\s0 protocol with
 the SSLs read and write BIOs. If an \s-1SSL\s0 connection is not established
@@ -274,81 +273,53 @@ unencrypted example in \fIBIO_s_connect\fR\|(3).
 \& char tmpbuf[1024];
 \& SSL_CTX *ctx;
 \& SSL *ssl;
-.Ve
-.PP
-.Vb 3
+\&
 \& ERR_load_crypto_strings();
 \& ERR_load_SSL_strings();
 \& OpenSSL_add_all_algorithms();
-.Ve
-.PP
-.Vb 3
-\& /* We would seed the PRNG here if the platform didn't
+\&
+\& /* We would seed the PRNG here if the platform didn\*(Aqt
 \&  * do it automatically
 \&  */
-.Ve
-.PP
-.Vb 1
+\&
 \& ctx = SSL_CTX_new(SSLv23_client_method());
-.Ve
-.PP
-.Vb 4
-\& /* We'd normally set some stuff like the verify paths and
+\&
+\& /* 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.
 \&  */
-.Ve
-.PP
-.Vb 1
+\&
 \& sbio = BIO_new_ssl_connect(ctx);
-.Ve
-.PP
-.Vb 1
+\&
 \& BIO_get_ssl(sbio, &ssl);
-.Ve
-.PP
-.Vb 4
+\&
 \& if(!ssl) {
-\&   fprintf(stderr, "Can't locate SSL pointer\en");
+\&   fprintf(stderr, "Can\*(Aqt locate SSL pointer\en");
 \&   /* whatever ... */
 \& }
-.Ve
-.PP
-.Vb 2
-\& /* Don't want any retries */
+\&
+\& /* Don\*(Aqt want any retries */
 \& SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
-.Ve
-.PP
-.Vb 1
+\&
 \& /* We might want to do other things with ssl here */
-.Ve
-.PP
-.Vb 1
+\&
 \& BIO_set_conn_hostname(sbio, "localhost:https");
-.Ve
-.PP
-.Vb 6
+\&
 \& 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 ... */
 \& }
-.Ve
-.PP
-.Vb 5
+\&
 \& if(BIO_do_handshake(sbio) <= 0) {
 \&        fprintf(stderr, "Error establishing SSL connection\en");
 \&        ERR_print_errors_fp(stderr);
 \&        /* whatever ... */
 \& }
-.Ve
-.PP
-.Vb 1
+\&
 \& /* Could examine ssl here to get connection info */
-.Ve
-.PP
-.Vb 8
+\&
 \& BIO_puts(sbio, "GET / HTTP/1.0\en\en");
 \& for(;;) {      
 \&        len = BIO_read(sbio, tmpbuf, 1024);
@@ -370,163 +341,107 @@ a client and also echoes the request to standard output.
 \& char tmpbuf[1024];
 \& SSL_CTX *ctx;
 \& SSL *ssl;
-.Ve
-.PP
-.Vb 3
+\&
 \& ERR_load_crypto_strings();
 \& ERR_load_SSL_strings();
 \& OpenSSL_add_all_algorithms();
-.Ve
-.PP
-.Vb 1
+\&
 \& /* Might seed PRNG here */
-.Ve
-.PP
-.Vb 1
+\&
 \& ctx = SSL_CTX_new(SSLv23_server_method());
-.Ve
-.PP
-.Vb 3
+\&
 \& 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)) {
-.Ve
-.PP
-.Vb 4
+\&
 \&        fprintf(stderr, "Error setting up SSL_CTX\en");
 \&        ERR_print_errors_fp(stderr);
 \&        return 0;
 \& }
-.Ve
-.PP
-.Vb 3
+\&
 \& /* Might do other things here like setting verify locations and
 \&  * DH and/or RSA temporary key callbacks
 \&  */
-.Ve
-.PP
-.Vb 2
+\&
 \& /* New SSL BIO setup as server */
 \& sbio=BIO_new_ssl(ctx,0);
-.Ve
-.PP
-.Vb 1
+\&
 \& BIO_get_ssl(sbio, &ssl);
-.Ve
-.PP
-.Vb 4
+\&
 \& if(!ssl) {
-\&   fprintf(stderr, "Can't locate SSL pointer\en");
+\&   fprintf(stderr, "Can\*(Aqt locate SSL pointer\en");
 \&   /* whatever ... */
 \& }
-.Ve
-.PP
-.Vb 2
-\& /* Don't want any retries */
+\&
+\& /* Don\*(Aqt want any retries */
 \& SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
-.Ve
-.PP
-.Vb 1
+\&
 \& /* Create the buffering BIO */
-.Ve
-.PP
-.Vb 1
+\&
 \& bbio = BIO_new(BIO_f_buffer());
-.Ve
-.PP
-.Vb 2
+\&
 \& /* Add to chain */
 \& sbio = BIO_push(bbio, sbio);
-.Ve
-.PP
-.Vb 1
+\&
 \& acpt=BIO_new_accept("4433");
-.Ve
-.PP
-.Vb 5
+\&
 \& /* 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
+\&  * BIO chain is now \*(Aqswallowed\*(Aq by the accept BIO and
 \&  * will be freed when the accept BIO is freed. 
 \&  */
-.Ve
-.PP
-.Vb 1
+\& 
 \& BIO_set_accept_bios(acpt,sbio);
-.Ve
-.PP
-.Vb 1
+\&
 \& out = BIO_new_fp(stdout, BIO_NOCLOSE);
-.Ve
-.PP
-.Vb 6
+\&
 \& /* Setup accept BIO */
 \& if(BIO_do_accept(acpt) <= 0) {
 \&        fprintf(stderr, "Error setting up accept BIO\en");
 \&        ERR_print_errors_fp(stderr);
 \&        return 0;
 \& }
-.Ve
-.PP
-.Vb 6
+\&
 \& /* Now wait for incoming connection */
 \& if(BIO_do_accept(acpt) <= 0) {
 \&        fprintf(stderr, "Error in connection\en");
 \&        ERR_print_errors_fp(stderr);
 \&        return 0;
 \& }
-.Ve
-.PP
-.Vb 3
+\&
 \& /* We only want one connection so remove and free
 \&  * accept BIO
 \&  */
-.Ve
-.PP
-.Vb 1
+\&
 \& sbio = BIO_pop(acpt);
-.Ve
-.PP
-.Vb 1
+\&
 \& BIO_free_all(acpt);
-.Ve
-.PP
-.Vb 5
+\&
 \& if(BIO_do_handshake(sbio) <= 0) {
 \&        fprintf(stderr, "Error in SSL handshake\en");
 \&        ERR_print_errors_fp(stderr);
 \&        return 0;
 \& }
-.Ve
-.PP
-.Vb 3
-\& BIO_puts(sbio, "HTTP/1.0 200 OK\er\enContent-type: text/plain\er\en\er\en");
+\&
+\& 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");
-.Ve
-.PP
-.Vb 8
+\& 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;
+\&        if((tmpbuf[0] == \*(Aq\er\*(Aq) || (tmpbuf[0] == \*(Aq\en\*(Aq)) break;
 \& }
-.Ve
-.PP
-.Vb 2
-\& BIO_puts(sbio, "--------------------------------------------------\er\en");
+\&
+\& BIO_puts(sbio, "\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\er\en");
 \& BIO_puts(sbio, "\er\en");
-.Ve
-.PP
-.Vb 2
+\&
 \& /* Since there is a buffering BIO present we had better flush it */
 \& BIO_flush(sbio);
-.Ve
-.PP
-.Vb 1
+\&
 \& BIO_free_all(sbio);
 .Ve
 .SH "SEE ALSO"