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 /doc/ssl | |
parent | 72660f5f15fcd71215193f993dd95da0d130168a (diff) | |
download | openssl-cc99526db1ee5b948736f6b07958a786fec1240b.tar.gz |
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>
Diffstat (limited to 'doc/ssl')
-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 |
15 files changed, 734 insertions, 0 deletions
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-negotiation is possible, a +call to SSL_write() can also cause write operations! The calling process +then must repeat the call after taking appropriate action to satisfy the +needs of SSL_write(). 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 write operation was successfull, the return value is the number of +bytes actually written to the TLS connection. + +=item 0 + +The write operation was not successfull. 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_read(3)|SSL_read(3)>, +L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> + +=cut |