diff options
author | Richard Levitte <levitte@openssl.org> | 2000-09-14 13:11:56 +0000 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2000-09-14 13:11:56 +0000 |
commit | cc99526db1ee5b948736f6b07958a786fec1240b (patch) | |
tree | 24c07af7e38f014e2baa02ba5ce454e24d64211f | |
parent | 72660f5f15fcd71215193f993dd95da0d130168a (diff) |
Add a number of documentation files, mostly for SSL routines, but also
for a few BIO routines.
Submitted by Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>
-rw-r--r-- | CHANGES | 3 | ||||
-rw-r--r-- | doc/crypto/BIO_ctrl_get_read_request.pod | 38 | ||||
-rw-r--r-- | doc/crypto/BIO_ctrl_pending.pod | 36 | ||||
-rw-r--r-- | doc/crypto/BIO_new_bio_pair.pod | 102 | ||||
-rw-r--r-- | doc/ssl/SSL_SESSION_free.pod | 25 | ||||
-rw-r--r-- | doc/ssl/SSL_accept.pod | 69 | ||||
-rw-r--r-- | doc/ssl/SSL_clear.pod | 39 | ||||
-rw-r--r-- | doc/ssl/SSL_connect.pod | 66 | ||||
-rw-r--r-- | doc/ssl/SSL_free.pod | 33 | ||||
-rw-r--r-- | doc/ssl/SSL_get_fd.pod | 44 | ||||
-rw-r--r-- | doc/ssl/SSL_get_rbio.pod | 40 | ||||
-rw-r--r-- | doc/ssl/SSL_get_session.pod | 48 | ||||
-rw-r--r-- | doc/ssl/SSL_new.pod | 42 | ||||
-rw-r--r-- | doc/ssl/SSL_read.pod | 67 | ||||
-rw-r--r-- | doc/ssl/SSL_set_bio.pod | 34 | ||||
-rw-r--r-- | doc/ssl/SSL_set_fd.pod | 54 | ||||
-rw-r--r-- | doc/ssl/SSL_set_session.pod | 45 | ||||
-rw-r--r-- | doc/ssl/SSL_shutdown.pod | 62 | ||||
-rw-r--r-- | doc/ssl/SSL_write.pod | 66 |
19 files changed, 913 insertions, 0 deletions
@@ -4,6 +4,9 @@ Changes between 0.9.5a and 0.9.6 [xx XXX 2000] + *) Add a large number of documentation files for many SSL routines. + [Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>] + *) Add a configuration entry for Sony News 4. [NAKAJI Hiroyuki <nakaji@tutrp.tut.ac.jp>] diff --git a/doc/crypto/BIO_ctrl_get_read_request.pod b/doc/crypto/BIO_ctrl_get_read_request.pod new file mode 100644 index 0000000000..4325fd16f8 --- /dev/null +++ b/doc/crypto/BIO_ctrl_get_read_request.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + + BIO_ctrl_get_read_request - Find out how much bytes are were requested from the BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + size_t BIO_ctrl_get_read_request(BIO *bio); + +=head1 DESCRIPTION + +BIO_ctrl_get_read_request() returns the number of bytes that were last +requested from B<bio> by a BIO_read() operation. This is useful e.g. for +BIO pairs, so that the application knows how much bytes to supply to B<bio>. + +=head1 BUGS + +When B<bio> is NULL, the OpenSSL library calls assert(). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item E<gt>=0 + +The number of bytes requested. + +=back + +=head1 SEE ALSO + +L<bio(3)|bio(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>, +L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)> diff --git a/doc/crypto/BIO_ctrl_pending.pod b/doc/crypto/BIO_ctrl_pending.pod new file mode 100644 index 0000000000..2351191300 --- /dev/null +++ b/doc/crypto/BIO_ctrl_pending.pod @@ -0,0 +1,36 @@ +=pod + +=head1 NAME + +BIO_ctrl_pending - Find out how much bytes are buffered in a BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + size_t BIO_ctrl_pending(BIO *bio); + +=head1 DESCRIPTION + +BIO_ctrl_pending() returns the number of bytes buffered in a BIO. + +=head1 BUGS + +When B<bio> is NULL, the OpenSSL library calls assert(). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item E<gt>=0 + +The number of bytes pending the BIO. + +=back + +=head1 SEE ALSO + +L<bio(3)|bio(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>, +L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)> diff --git a/doc/crypto/BIO_new_bio_pair.pod b/doc/crypto/BIO_new_bio_pair.pod new file mode 100644 index 0000000000..c331bd02b8 --- /dev/null +++ b/doc/crypto/BIO_new_bio_pair.pod @@ -0,0 +1,102 @@ +=pod + +=head1 NAME + +BIO_new_bio_pair - create a new BIO pair + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); + +=head1 DESCRIPTION + +BIO_new_bio_pair() creates a buffering BIO pair. It has two endpoints between +data can be buffered. Its typical use is to connect one endpoint as underlying +input/output BIO to an SSL and access the other one controlled by the program +instead of accessing the network connection directly. + +The two new BIOs B<bio1> and B<bio2> are symmetric with respect to their +functionality. The size of their buffers is determined by B<writebuf1> and +B<writebuf2>. If the size give is 0, the default size is used. + +BIO_new_bio_pair() does not check whether B<bio1> or B<bio2> do point to +some other BIO, the values are overwritten, BIO_free() is not called. + +The two BIOs, even though forming a BIO pair and must be BIO_free()'ed +seperately. This can be of importance, as some SSL-functions like SSL_set_bio() +or SSL_free() call BIO_free() implicitely, so that the peer-BIO is left +untouched and must also be BIO_free()'ed. + +=head1 EXAMPLE + +The BIO pair can be used to have full control over the network access of an +application. The application can call select() on the socket as required +without having to go through the SSL-interface. + + BIO *internal_bio, *network_bio; + ... + BIO_new_bio_pair(internal_bio, 0, network_bio, 0); + SSL_set_bio(ssl, internal_bio); + SSL_operations(); + ... + + application | TLS-engine + | | + +----------> SSL_operations() + | /\ || + | || \/ + | BIO-pair (internal_bio) + +----------< BIO-pair (network_bio) + | | + socket | + + ... + SSL_free(ssl); /* implicitely frees internal_bio */ + BIO_free(network_bio); + ... + +As the BIO pair will only buffer the data and never directly access the +connection, it behaves non-blocking and will return as soon as the write +buffer is full or the read buffer is drained. Then the application has to +flush the write buffer and/or fill the read buffer. + +Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO +and must be transfered to the network. Use BIO_ctrl_get_read_request() to +find out, how many bytes must be written into the buffer before the +SSL_operation() can successfully be continued. + +=head1 IMPORTANT + +As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ +condition, but there is still data in the write buffer. An application must +not rely on the error value of SSL_operation() but must assure that the +write buffer is always flushed first. Otherwise a deadlock may occur as +the peer might be waiting for the data before being able to continue. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 1 + +The BIO pair was created successfully. The new BIOs are available in +B<bio1> and B<bio2>. + +=item 0 + +The operation failed. The NULL pointer is stored into the locations for +B<bio1> and B<bio2>. Check the error stack for more information. + +=back + +=head1 SEE ALSO + +L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, +L<BIO_ctrl_pending(3)|BIO_ctrl_pending(3)>, +L<BIO_ctrl_get_read_request(3)|BIO_ctrl_get_read_request(3)> + +=cut diff --git a/doc/ssl/SSL_SESSION_free.pod b/doc/ssl/SSL_SESSION_free.pod new file mode 100644 index 0000000000..2ec7544cac --- /dev/null +++ b/doc/ssl/SSL_SESSION_free.pod @@ -0,0 +1,25 @@ +=pod + +=head1 NAME + +SSL_SESSION_free - Free up an allocated SSL_SESSION structure + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void *SSL_SESSION_free(SSL_SESSION *session); + +=head1 DESCRIPTION + +SSL_SESSION_free() decrements the reference count of B<session> and removes +the SSL_SESSION structure pointed to by B<session> and frees up the allocated +memory, if the the reference count has reached 0. + +=head1 RETURN VALUES + +SSL_SESSION_free() does not provide diagnostic information. + +L<ssl(3)|ssl(3)>, L<SSL_get_session(3)|SSL_get_session(3)> + +=cut diff --git a/doc/ssl/SSL_accept.pod b/doc/ssl/SSL_accept.pod new file mode 100644 index 0000000000..d21a391cb8 --- /dev/null +++ b/doc/ssl/SSL_accept.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + +SSL_accept - Wait for a TLS client to initiate a TLS handshake + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_accept(SSL *ssl); + +=head1 DESCRIPTION + +SSL_accept() waits for a TLS client to initiate the TLS handshake. +The communication channel must already have been set and assigned to the +B<ssl> by setting an underlying B<BIO>. The behaviour of SSL_accept() depends +on the underlying BIO. + +If the underlying BIO is B<blocking>, SSL_accept() will only return, once the +handshake has been finished or an error occured, except for SGC (Server +Gated Cryptography). For SGC SSL_accept() may return with -1 but +SSL_get_error() will yield SSL_ERROR_WANT_READ/WRITE and SSL_accept() +should be called again. + +If the underlying BIO is B<non-blocking>, SSL_accept() will also return, +when the underlying BIO could not satisfy the needs of SSL_accept() +to continue the handshake. In this case a call to SSL_get_error() with the +return value of SSL_accept() will yield SSL_ERROR_WANT_READ or +SSL_ERROR_WANT_WRITE. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_accept(). +The action depends on the underlying BIO. When using a non-blocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 1 + +The TLS handshake was successfully completed, a TLS connection has been +established. + +=item 0 + +The TLS handshake was not successfull but was shut down controlled and +by the specifications of the TLS protocol. Call SSL_get_error() with the +return value B<ret> to find out the reason. + +=item -1 + +The TLS handshake was not successfull, because a fatal error occured either +at the protocol level or a connection failure occured. The shutdown was +not clean. It can also occure of action is need to continue the operation +for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> +to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, +L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_clear.pod b/doc/ssl/SSL_clear.pod new file mode 100644 index 0000000000..c68938b4bc --- /dev/null +++ b/doc/ssl/SSL_clear.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +SSL_clear - Reset SSL to allow another connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int *SSL_clear(SSL *ssl); + +=head1 DESCRIPTION + +Reset the B<ssl> to allow another connection. All settings (method, ciphers, +BIOs) are kept. A completely negotiated SSL_SESSION is not freed but left +untouched for the underlying SSL_CTX. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 0 + +The SSL_clear() operation could not be performed. Check the error stack to +find out the reason. + +=item 1 + +The SSL_clear() operation was successfull. + +=back + +L<SSL_new(3)|SSL_new(3)>, L<SSL_free(3)|SSL_free(3)>, +L<ssl(3)|ssl(3)> + +=cut diff --git a/doc/ssl/SSL_connect.pod b/doc/ssl/SSL_connect.pod new file mode 100644 index 0000000000..269edd0e70 --- /dev/null +++ b/doc/ssl/SSL_connect.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +SSL_connect - Initiate the TLS handshake with an TLS server + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_connect(SSL *ssl); + +=head1 DESCRIPTION + +SSL_connect() initiates the TLS handshake with a server. The communication +channel must already have been set and assigned to the B<ssl> by setting an +underlying B<BIO>. The behaviour of SSL_connect() depends on the underlying +BIO. + +If the underlying BIO is B<blocking>, SSL_connect() will only return, once the +handshake has been finished or an error occured. + +If the underlying BIO is B<non-blocking>, SSL_connect() will also return, +when the underlying BIO could not satisfy the needs of SSL_connect() +to continue the handshake. In this case a call to SSL_get_error() with the +return value of SSL_connect() will yield SSL_ERROR_WANT_READ or +SSL_ERROR_WANT_WRITE. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_connect(). +The action depends on the underlying BIO. When using a non-blocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 1 + +The TLS handshake was successfully completed, a TLS connection has been +established. + +=item 0 + +The TLS handshake was not successfull but was shut down controlled and +by the specifications of the TLS protocol. Call SSL_get_error() with the +return value B<ret> to find out the reason. + +=item -1 + +The TLS handshake was not successfull, because a fatal error occured either +at the protocol level or a connection failure occured. The shutdown was +not clean. It can also occure of action is need to continue the operation +for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> +to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_accept(3)|SSL_accept(3)>, +L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_free.pod b/doc/ssl/SSL_free.pod new file mode 100644 index 0000000000..3d01234a85 --- /dev/null +++ b/doc/ssl/SSL_free.pod @@ -0,0 +1,33 @@ +=pod + +=head1 NAME + +SSL_free - Free up an allocated SSL structure + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void *SSL_free(SSL *ssl); + +=head1 DESCRIPTION + +SSL_free() decrements the reference count of B<ssl> and removes the SSL +structure pointed to by B<ssl> and frees up the allocated memory, if the +the reference count has reached 0. + +It also calls the free()ing procedures for indirectly affected items, if +applicable: the buffering BIO, the read and write BIOs, +cipher lists especially created for this B<ssl>, the SSL_SESSION. +Do not explicitly free these indirectly freed up items before or after +calling SSL_free(), as trying to free things twice may lead to program +failure. + +=head1 RETURN VALUES + +SSL_free() does not provide diagnostic information. + +L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, +L<ssl(3)|ssl(3)> + +=cut diff --git a/doc/ssl/SSL_get_fd.pod b/doc/ssl/SSL_get_fd.pod new file mode 100644 index 0000000000..0ed21d5f15 --- /dev/null +++ b/doc/ssl/SSL_get_fd.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +SSL_get_fd - Get file descriptor linked to an SSL + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_get_fd(SSL *ssl); + int SSL_get_rfd(SSL *ssl); + int SSL_get_wfd(SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_fd() returns the file descriptor which is linked to B<ssl>. +SSL_get_rfd() and SSL_get_wfd() return the file descriptors for the +read or the write channel, which can be different. If the read and the +write channel are different, SSL_get_fd() will return the file descriptor +of the read channel. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item -1 + +The operation failed, because the underlying BIO is not of the correct type +(suitable for file descriptors). + +=item E<gt>=0 + +The file descriptor linked to B<ssl>. + +=back + +=head1 SEE ALSO + +L<SSL_set_fd(3)|SSL_set_fd(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_get_rbio.pod b/doc/ssl/SSL_get_rbio.pod new file mode 100644 index 0000000000..40a5f12e71 --- /dev/null +++ b/doc/ssl/SSL_get_rbio.pod @@ -0,0 +1,40 @@ +=pod + +=head1 NAME + +SSL_get_rbio - Get BIO linked to an SSL + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + BIO *SSL_get_rbio(SSL *ssl); + BIO *SSL_get_wbio(SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_rbio() and SSL_get_wbio() return pointers to the BIOs for the +read or the write channel, which can be different. The reference count +of the BIO is not incremented. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +No BIO was connected to the SSL + +=item Any other pointer + +The BIO linked to B<ssl>. + +=back + +=head1 SEE ALSO + +L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_get_session.pod b/doc/ssl/SSL_get_session.pod new file mode 100644 index 0000000000..0b3f50af42 --- /dev/null +++ b/doc/ssl/SSL_get_session.pod @@ -0,0 +1,48 @@ +=pod + +=head1 NAME + +SSL_get_session - Retrieve SSL session data + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_SESSION *SSL_get_session(SSL *ssl); + SSL_SESSION *SSL_get0_session(SSL *ssl); + SSL_SESSION *SSL_get1_session(SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_session() returns a pointer to the SSL session actually used in +B<ssl>. The reference count of the SSL session is not incremented, so +that the pointer can become invalid when the B<ssl> is freed and +SSL_SESSION_free() is implicitly called. + +SSL_get0_session() is the same as SSL_get_session(). + +SSL_get1_session() is the same as SSL_get_session(), but the reference +count of the SSL session is incremented by one. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +There is no session available in B<ssl>. + +=item Pointer to an SSL + +The return value points to the data of an SSL session. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_free(3)|SSL_free(3)>, +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> + +=cut diff --git a/doc/ssl/SSL_new.pod b/doc/ssl/SSL_new.pod new file mode 100644 index 0000000000..a393c94c02 --- /dev/null +++ b/doc/ssl/SSL_new.pod @@ -0,0 +1,42 @@ +=pod + +=head1 NAME + +SSL_new - Create a new SSL structure for a connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL *SSL_new(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_new() creates a new B<SSL> structure which is needed to hold the data +for a SSL connection. The new SSL inherits the settings of the underlying +context B<ctx>: connection method (SSLv2/v3/TLSv1), options, verification +settings, timeout settings. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +The creation of a new SSL failed. Check the error stack to find out the +reason. + +=item Pointer to an SSL + +The return value points to an allocated SSL structure. + +=back + +=head1 SEE ALSO + +L<SSL_free(3)|SSL_free(3)>, L<SSL_clear(3)|SSL_clear(3)>, +L<ssl(3)|ssl(3)> + +=cut diff --git a/doc/ssl/SSL_read.pod b/doc/ssl/SSL_read.pod new file mode 100644 index 0000000000..9df51030c5 --- /dev/null +++ b/doc/ssl/SSL_read.pod @@ -0,0 +1,67 @@ +=pod + +=head1 NAME + +SSL_read - Read bytes from a TLS connection. + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_read(SSL *ssl, char *buf, int num); + +=head1 DESCRIPTION + +SSL_read() tries to read B<num> bytes from the specified B<ssl> into the +buffer B<buf>. If necessary, SSL_read() will negotiate a TLS session, if +not already explicitely performed by SSL_connect() or SSL_accept(). If the +peer requests a re-negotiation, it will be performed transparently during +the SSL_read() operation. The behaviour of SSL_read() depends on the +underlying BIO. + +If the underlying BIO is B<blocking>, SSL_read() will only return, once the +read operation has been finished or an error occured. + +If the underlying BIO is B<non-blocking>, SSL_read() will also return, +when the underlying BIO could not satisfy the needs of SSL_read() +to continue the operation. In this case a call to SSL_get_error() with the +return value of SSL_read() will yield SSL_ERROR_WANT_READ or +SSL_ERROR_WANT_WRITE. As at any time a re-negotiation is possible, a +call to SSL_read() can also cause write operations! The calling process +then must repeat the call after taking appropriate action to satisfy the +needs of SSL_read(). The action depends on the underlying BIO. When using a +non-blocking socket, nothing is to be done, but select() can be used to check +for the required condition. When using a buffering BIO, like a BIO pair, data +must be written into or retrieved out of the BIO before being able to continue. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item E<gt>0 + +The read operation was successfull, the return value is the number of +bytes actually read from the TLS connection. + +=item 0 + +The read operation was not successfull, probably because no data was +available. Call SSL_get_error() with the return value B<ret> to find out, +whether an error occured. + +=item -1 + +The read operation was not successfull, because either an error occured +or action must be taken by the calling process. Call SSL_get_error() with the +return value B<ret> to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>, +L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_set_bio.pod b/doc/ssl/SSL_set_bio.pod new file mode 100644 index 0000000000..24fa77e71d --- /dev/null +++ b/doc/ssl/SSL_set_bio.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +SSL_set_bio - Connect the SSL with a BIO + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio); + +=head1 DESCRIPTION + +SSL_set_bio() connects the BIOs B<rbio> and B<wbio> for the read and write +operations of the TLS (encrypted) side of B<ssl>. + +The SSL engine inherits the behaviour of B<rbio> and B<wbio>, respectively. +If a BIO is non-blocking, the B<ssl> will also have non-blocking behaviour. + +If there was already a BIO connected to B<ssl>, BIO_free() will be called +(for both the reading and writing side, if different). + +=head1 RETURN VALUES + +SSL_set_bio() cannot fail. + +=head1 SEE ALSO + +L<SSL_get_rbio(3)|SSL_get_rbio(3)>, +L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>, +L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_set_fd.pod b/doc/ssl/SSL_set_fd.pod new file mode 100644 index 0000000000..076791e17b --- /dev/null +++ b/doc/ssl/SSL_set_fd.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +SSL_set_fd - Connect the SSL with a file descriptor + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_set_fd(SSL *ssl, int fd); + int SSL_set_rfd(SSL *ssl, int fd); + int SSL_set_wfd(SSL *ssl, int fd); + +=head1 DESCRIPTION + +SSL_set_fd() sets the file descriptor B<fd> as the input/output facility +for the TLS (encrypted) side of SSL engine. B<fd> will typically be the +socket file descriptor of a network connection. + +When performing the operation, a B<socket BIO> is automatically created to +interface between the B<ssl> and B<fd>. The BIO and hence the SSL engine +inherit the behaviour of B<fd>. If B<fd> is non-blocking, the B<ssl> will +also have non-blocking behaviour. + +If there was already a BIO connected to B<ssl>, BIO_free() will be called +(for both the reading and writing side, if different). + +SSL_set_rfd() and SSL_set_wfd() perform the respective action but only +for the read channel or the write channel, which can be set independantly. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 0 + +The operation failed. Check the error stack to find out why. + +=item 1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<SSL_get_fd(3)|SSL_get_fd(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>, +L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>, +L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_set_session.pod b/doc/ssl/SSL_set_session.pod new file mode 100644 index 0000000000..b1162ba61a --- /dev/null +++ b/doc/ssl/SSL_set_session.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +SSL_set_session - Set an SSL session to be used during SSL connect + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int *SSL_set_session(SSL *ssl, SSL_SESSION *session); + +=head1 DESCRIPTION + +SSL_set_session() sets B<session> to be used, when the SSL connection +is to be established. SSL_set_session() is only useful for SSL clients. +When the session is set, the reference count of B<session> is incremented +by 1. If the session is not reused, the reference count is decremented +again during SSL_connect(). + +If there is already a session set inside B<ssl> (because it was set with +SSL_set_session() before or because the same B<ssl> was already used for +a connection) SSL_SESSION_free() will be called for that session. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 0 + +The operation failed, check the error stack to find out the reason. + +=item 1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> + +=cut diff --git a/doc/ssl/SSL_shutdown.pod b/doc/ssl/SSL_shutdown.pod new file mode 100644 index 0000000000..be1166b596 --- /dev/null +++ b/doc/ssl/SSL_shutdown.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +SSL_shutdown - Shut down a TLS connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_shutdown(SSL *ssl); + +=head1 DESCRIPTION + +SSL_shutdown() shuts down an active TLS connection. It sends the shutdown +alert to the peer. The behaviour of SSL_shutdown() depends on the underlying +BIO. + +If the underlying BIO is B<blocking>, SSL_shutdown() will only return, once the +handshake has been finished or an error occured. + +If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return, +when the underlying BIO could not satisfy the needs of SSL_shutdown() +to continue the handshake. In this case a call to SSL_get_error() with the +return value of SSL_shutdown() will yield SSL_ERROR_WANT_READ or +SSL_ERROR_WANT_WRITE. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_shutdown(). +The action depends on the underlying BIO. When using a non-blocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 1 + +The shutdown was successfully completed. + +=item 0 + +The shutdown was not successfull. Call SSL_get_error() with the return +value B<ret> to find out the reason. + +=item -1 + +The shutdown was not successfull, because a fatal error occured either +at the protocol level or a connection failure occured. It can also occure of +action is need to continue the operation for non-blocking BIOs. +Call SSL_get_error() with the return value B<ret> to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, +L<SSL_accept(3)|SSL_accept(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_write.pod b/doc/ssl/SSL_write.pod new file mode 100644 index 0000000000..9b433c0e2d --- /dev/null +++ b/doc/ssl/SSL_write.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +SSL_read - Write bytes to a TLS connection. + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_write(SSL *ssl, char *buf, int num); + +=head1 DESCRIPTION + +SSL_write() writes B<num> bytes from the buffer B<buf> into the specified +B<ssl>. If necessary, SSL_write() will negotiate a TLS session, if +not already explicitely performed by SSL_connect() or SSL_accept(). If the +peer requests a re-negotiation, it will be performed transparently during +the SSL_write() operation. The behaviour of SSL_write() depends on the +underlying BIO. + +If the underlying BIO is B<blocking>, SSL_write() will only return, once the +write operation has been finished or an error occured. + +If the underlying BIO is B<non-blocking>, SSL_write() will also return, +when the underlying BIO could not satisfy the needs of SSL_write() +to continue the operation. In this case a call to SSL_get_error() with the +return value of SSL_write() will yield SSL_ERROR_WANT_READ or +SSL_ERROR_WANT_WRITE. As at any time a re-negotiatio |