diff options
| -rw-r--r-- | doc/crypto/BIO_ctrl.pod | 9 | ||||
| -rw-r--r-- | doc/crypto/BIO_f_ssl.pod | 175 | ||||
| -rw-r--r-- | doc/crypto/BIO_read.pod | 3 |
3 files changed, 186 insertions, 1 deletions
diff --git a/doc/crypto/BIO_ctrl.pod b/doc/crypto/BIO_ctrl.pod index 5ef27f487e..aed2095925 100644 --- a/doc/crypto/BIO_ctrl.pod +++ b/doc/crypto/BIO_ctrl.pod @@ -91,6 +91,15 @@ case of a file BIO some data may be available in the FILE structures internal buffers but it is not possible to determine this in a portably way. For other types of BIO they may not be supported. +Filter BIOs if the do not internally handle a particular BIO_ctrl() +operation usually pass the operation to the next BIO in the chain. +This often means there is no need to locate the required BIO for +a particular operation, it can be called on a chain and it will +be automatically passed to the relevant BIO. + +Source/sink BIOs will return an error if the do not recognise the +BIO_ctrl() operation. + =head1 SEE ALSO TBA diff --git a/doc/crypto/BIO_f_ssl.pod b/doc/crypto/BIO_f_ssl.pod new file mode 100644 index 0000000000..4ae4400427 --- /dev/null +++ b/doc/crypto/BIO_f_ssl.pod @@ -0,0 +1,175 @@ +=pod + +=head1 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 + +=head1 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); + +=head1 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 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 typically disconnect the underlying transport. +The SSL BIO is then reset to the initial accept or connect state. + +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<b> to B<ssl> using +the close flag B<c>. + +BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be +manipulated using the standard SSL library functions. + +BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client> +is 1 client mode is set. If B<client> is 0 server mode is set. + +BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count +to B<num>. When set after every B<num> bytes of I/O (read and write) +the SSL session is automatically renegotiated. B<num> must be at +least 512 bytes. + +BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to +B<seconds>. When the renegotiate timeout elapses the sesssion 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 B<ctx> and using +client mode if B<client> is non zero. + +BIO_new_ssl_connect() creates a new BIO chain consisting of an +SSL BIO (using B<ctx>) followed by a connect BIO. + +BIO_new_buffer_ssl_connect() creates a new BIO chain consisting +of a buffering BIO, an SSL BIO (using B<ctx>) and a connect +BIO. + +BIO_ssl_copy_session_id() copies an SSL session id between +BIO chains B<from> and B<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 B<bio>. It does this by locating the SSL BIO in the +chain and calling SSL_shutdown() on its internal SSL +pointer. + +=head1 NOTES + +SSL BIOs 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 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 filter +BIOs the servers name and port can be set using BIO_set_host() +on the BIO returned by BIO_new_ssl_connect() without having +to locate the connect BIO first. + +=head1 RETURN VALUES + +TBA + +=head1 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 L<BIO_s_connect(3)|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(); + + 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\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 ... */ + } + + /* 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); + +=head1 SEE ALSO + +TBA diff --git a/doc/crypto/BIO_read.pod b/doc/crypto/BIO_read.pod index 563806c206..d9311708ab 100644 --- a/doc/crypto/BIO_read.pod +++ b/doc/crypto/BIO_read.pod @@ -52,7 +52,7 @@ I/O structure and may block as a result. Instead select() (or equivalent) should be combined with non blocking I/O so successive reads will request a retry instead of blocking. -See the L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to +See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to determine the cause of a retry and other I/O issues. If the BIO_gets() function is not supported by a BIO then it possible to @@ -60,6 +60,7 @@ work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)> to the chain. =head1 SEE ALSO + L<BIO_should_retry(3)|BIO_should_retry(3)> TBA |