From cc99526db1ee5b948736f6b07958a786fec1240b Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Thu, 14 Sep 2000 13:11:56 +0000 Subject: [PATCH 1/1] Add a number of documentation files, mostly for SSL routines, but also for a few BIO routines. Submitted by Lutz Jaenicke --- CHANGES | 3 + doc/crypto/BIO_ctrl_get_read_request.pod | 38 +++++++++ doc/crypto/BIO_ctrl_pending.pod | 36 ++++++++ doc/crypto/BIO_new_bio_pair.pod | 102 +++++++++++++++++++++++ doc/ssl/SSL_SESSION_free.pod | 25 ++++++ doc/ssl/SSL_accept.pod | 69 +++++++++++++++ doc/ssl/SSL_clear.pod | 39 +++++++++ doc/ssl/SSL_connect.pod | 66 +++++++++++++++ doc/ssl/SSL_free.pod | 33 ++++++++ doc/ssl/SSL_get_fd.pod | 44 ++++++++++ doc/ssl/SSL_get_rbio.pod | 40 +++++++++ doc/ssl/SSL_get_session.pod | 48 +++++++++++ doc/ssl/SSL_new.pod | 42 ++++++++++ doc/ssl/SSL_read.pod | 67 +++++++++++++++ doc/ssl/SSL_set_bio.pod | 34 ++++++++ doc/ssl/SSL_set_fd.pod | 54 ++++++++++++ doc/ssl/SSL_set_session.pod | 45 ++++++++++ doc/ssl/SSL_shutdown.pod | 62 ++++++++++++++ doc/ssl/SSL_write.pod | 66 +++++++++++++++ 19 files changed, 913 insertions(+) create mode 100644 doc/crypto/BIO_ctrl_get_read_request.pod create mode 100644 doc/crypto/BIO_ctrl_pending.pod create mode 100644 doc/crypto/BIO_new_bio_pair.pod create mode 100644 doc/ssl/SSL_SESSION_free.pod create mode 100644 doc/ssl/SSL_accept.pod create mode 100644 doc/ssl/SSL_clear.pod create mode 100644 doc/ssl/SSL_connect.pod create mode 100644 doc/ssl/SSL_free.pod create mode 100644 doc/ssl/SSL_get_fd.pod create mode 100644 doc/ssl/SSL_get_rbio.pod create mode 100644 doc/ssl/SSL_get_session.pod create mode 100644 doc/ssl/SSL_new.pod create mode 100644 doc/ssl/SSL_read.pod create mode 100644 doc/ssl/SSL_set_bio.pod create mode 100644 doc/ssl/SSL_set_fd.pod create mode 100644 doc/ssl/SSL_set_session.pod create mode 100644 doc/ssl/SSL_shutdown.pod create mode 100644 doc/ssl/SSL_write.pod diff --git a/CHANGES b/CHANGES index c0bb751578..aeb40d2184 100644 --- a/CHANGES +++ b/CHANGES @@ -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 ] + *) Add a configuration entry for Sony News 4. [NAKAJI Hiroyuki ] 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 + + 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 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. + +=head1 BUGS + +When B is NULL, the OpenSSL library calls assert(). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item E=0 + +The number of bytes requested. + +=back + +=head1 SEE ALSO + +L, L, +L 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 + + 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 is NULL, the OpenSSL library calls assert(). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item E=0 + +The number of bytes pending the BIO. + +=back + +=head1 SEE ALSO + +L, L, +L 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 + + 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 and B are symmetric with respect to their +functionality. The size of their buffers is determined by B and +B. If the size give is 0, the default size is used. + +BIO_new_bio_pair() does not check whether B or B 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 and B. + +=item 0 + +The operation failed. The NULL pointer is stored into the locations for +B and B. Check the error stack for more information. + +=back + +=head1 SEE ALSO + +L, L, L, +L, +L + +=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 + + void *SSL_SESSION_free(SSL_SESSION *session); + +=head1 DESCRIPTION + +SSL_SESSION_free() decrements the reference count of B and removes +the SSL_SESSION structure pointed to by B 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, L + +=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 + + 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 by setting an underlying B. The behaviour of SSL_accept() depends +on the underlying BIO. + +If the underlying BIO is B, 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, 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 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 +to find out the reason. + +=back + +=head1 SEE ALSO + +L, L, +L, L, L + +=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 + + int *SSL_clear(SSL *ssl); + +=head1 DESCRIPTION + +Reset the B 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, L, +L + +=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 + + 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 by setting an +underlying B. The behaviour of SSL_connect() depends on the underlying +BIO. + +If the underlying BIO is B, SSL_connect() will only return, once the +handshake has been finished or an error occured. + +If the underlying BIO is B, 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 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 +to find out the reason. + +=back + +=head1 SEE ALSO + +L, L, +L, L , L + +=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 + + void *SSL_free(SSL *ssl); + +=head1 DESCRIPTION + +SSL_free() decrements the reference count of B and removes the SSL +structure pointed to by B 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, 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, L, +L + +=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 + + 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_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=0 + +The file descriptor linked to B. + +=back + +=head1 SEE ALSO + +L, L , L + +=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 + + 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. + +=back + +=head1 SEE ALSO + +L, L , L + +=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 + + 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. The reference count of the SSL session is not incremented, so +that the pointer can become invalid when the B 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. + +=item Pointer to an SSL + +The return value points to the data of an SSL session. + +=back + +=head1 SEE ALSO + +L, L, +L + +=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 + + SSL *SSL_new(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_new() creates a new B structure which is needed to hold the data +for a SSL connection. The new SSL inherits the settings of the underlying +context B: 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, L, +L + +=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 + + int SSL_read(SSL *ssl, char *buf, int num); + +=head1 DESCRIPTION + +SSL_read() tries to read B bytes from the specified B into the +buffer B. 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, SSL_read() will only return, once the +read operation has been finished or an error occured. + +If the underlying BIO is B, 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 E0 + +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 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 to find out the reason. + +=back + +=head1 SEE ALSO + +L, L, +L, L + +=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 + + void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio); + +=head1 DESCRIPTION + +SSL_set_bio() connects the BIOs B and B for the read and write +operations of the TLS (encrypted) side of B. + +The SSL engine inherits the behaviour of B and B, respectively. +If a BIO is non-blocking, the B will also have non-blocking behaviour. + +If there was already a BIO connected to B, 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, +L, L, +L, L , L + +=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 + + 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 as the input/output facility +for the TLS (encrypted) side of SSL engine. B will typically be the +socket file descriptor of a network connection. + +When performing the operation, a B is automatically created to +interface between the B and B. The BIO and hence the SSL engine +inherit the behaviour of B. If B is non-blocking, the B will +also have non-blocking behaviour. + +If there was already a BIO connected to B, 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, L, +L, L, +L, L , L + +=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 + + int *SSL_set_session(SSL *ssl, SSL_SESSION *session); + +=head1 DESCRIPTION + +SSL_set_session() sets B 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 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 (because it was set with +SSL_set_session() before or because the same B 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, L + +=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 + + 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, SSL_shutdown() will only return, once the +handshake has been finished or an error occured. + +If the underlying BIO is B, 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 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 to find out the reason. + +=back + +=head1 SEE ALSO + +L, L, +L, L, L + +=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 + + int SSL_write(SSL *ssl, char *buf, int num); + +=head1 DESCRIPTION + +SSL_write() writes B bytes from the buffer B into the specified +B. 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, SSL_write() will only return, once the +write operation has been finished or an error occured. + +If the underlying BIO is B, 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 E0 + +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 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 to find out the reason. + +=back + +=head1 SEE ALSO + +L, L, +L, L + +=cut -- 2.34.1