Upgrade to OpenSSL 0.9.8h.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_f_ssl.3
index 3fefe93..47c4f0f 100644 (file)
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 2.12 (Pod::Simple 3.05)
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
 .\"
 .\" 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-
+.\" 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
 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 .ie n \{\
 .    ds -- \(*W-
 .    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
+.\"
 .\" 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
 .\" ========================================================================
 .\"
 .IX Title "BIO_f_ssl 3"
-.TH BIO_f_ssl 3 "2007-10-24" "0.9.8g" "OpenSSL"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.if n .ad l
-.nh
+.TH BIO_f_ssl 3 "2008-09-06" "0.9.8h" "OpenSSL"
 .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,
@@ -139,9 +140,13 @@ 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)
@@ -151,20 +156,24 @@ 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
@@ -265,53 +274,81 @@ 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
 \&  * 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
 \&  * 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");
 \&   /* whatever ... */
 \& }
-\&
+.Ve
+.PP
+.Vb 2
 \& /* Don't 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);
@@ -333,92 +370,142 @@ 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");
 \&   /* whatever ... */
 \& }
-\&
+.Ve
+.PP
+.Vb 2
 \& /* Don't 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
 \&  * 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;
 \& }
-\&
-\& BIO_puts(sbio, "HTTP/1.0 200 OK\er\enContent\-type: text/plain\er\en\er\en");
+.Ve
+.PP
+.Vb 3
+\& 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");
-\&
+\& BIO_puts(sbio, "--------------------------------------------------\er\en");
+.Ve
+.PP
+.Vb 8
 \& for(;;) {
 \&        len = BIO_gets(sbio, tmpbuf, 1024);
 \&        if(len <= 0) break;
@@ -427,13 +514,19 @@ a client and also echoes the request to standard output.
 \&        /* Look for blank line signifying end of headers*/
 \&        if((tmpbuf[0] == '\er') || (tmpbuf[0] == '\en')) break;
 \& }
-\&
-\& BIO_puts(sbio, "\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\er\en");
+.Ve
+.PP
+.Vb 2
+\& 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"