From 8de7587e02e5efc586cc61178ec170e7f67afe70 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Sun, 17 Sep 2000 00:10:29 +0000 Subject: [PATCH] Merge from main trunk. --- crypto/bio/bio.h | 1 + doc/apps/x509.pod | 2 +- doc/crypto/BIO_ctrl.pod | 34 +++++++++++++++----- doc/crypto/BIO_ctrl_get_read_request.pod | 38 ---------------------- doc/crypto/BIO_ctrl_pending.pod | 36 --------------------- doc/crypto/BIO_f_cipher.pod | 2 +- doc/crypto/BIO_f_md.pod | 2 +- doc/crypto/BIO_new.pod | 2 +- doc/crypto/BIO_new_bio_pair.pod | 6 ++-- doc/crypto/BIO_read.pod | 7 +++-- doc/crypto/BIO_s_accept.pod | 6 ++-- doc/crypto/BIO_s_bio.pod | 40 +++++++++++++++--------- doc/crypto/BIO_s_connect.pod | 8 ++--- doc/crypto/BIO_s_fd.pod | 35 ++++++++++----------- doc/crypto/BIO_s_file.pod | 35 ++++++++++++--------- doc/crypto/BIO_s_mem.pod | 4 +-- doc/crypto/BIO_s_socket.pod | 2 +- doc/crypto/BIO_seek.pod | 30 ------------------ doc/crypto/bio.pod | 14 ++++++++- doc/crypto/threads.pod | 2 +- doc/ssl/SSL_SESSION_free.pod | 4 +-- doc/ssl/SSL_accept.pod | 30 +++++++++--------- doc/ssl/SSL_clear.pod | 10 +++--- doc/ssl/SSL_connect.pod | 26 +++++++-------- doc/ssl/SSL_free.pod | 8 ++--- doc/ssl/SSL_get_error.pod | 20 ++++++------ doc/ssl/SSL_get_fd.pod | 2 +- doc/ssl/SSL_get_rbio.pod | 4 +-- doc/ssl/SSL_get_session.pod | 8 ++--- doc/ssl/SSL_new.pod | 16 +++++----- doc/ssl/SSL_read.pod | 24 +++++++------- doc/ssl/SSL_set_bio.pod | 6 ++-- doc/ssl/SSL_set_fd.pod | 8 ++--- doc/ssl/SSL_set_session.pod | 10 +++--- doc/ssl/SSL_shutdown.pod | 20 ++++++------ doc/ssl/SSL_write.pod | 22 ++++++------- doc/ssl/ssl.pod | 13 ++++++-- 37 files changed, 246 insertions(+), 291 deletions(-) delete mode 100644 doc/crypto/BIO_ctrl_get_read_request.pod delete mode 100644 doc/crypto/BIO_ctrl_pending.pod delete mode 100644 doc/crypto/BIO_seek.pod diff --git a/crypto/bio/bio.h b/crypto/bio/bio.h index fd23a15bc0..137fd0de48 100644 --- a/crypto/bio/bio.h +++ b/crypto/bio/bio.h @@ -474,6 +474,7 @@ size_t BIO_ctrl_wpending(BIO *b); #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL) #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2) #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL) +#define BIO_set_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL) /* macros with inappropriate type -- but ...pending macros use int too: */ #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL) #define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL) diff --git a/doc/apps/x509.pod b/doc/apps/x509.pod index 7f32eef000..84f76cb421 100644 --- a/doc/apps/x509.pod +++ b/doc/apps/x509.pod @@ -694,7 +694,7 @@ There should be options to explicitly set such things as start and end dates rather than an offset from the current time. The code to implement the verify behaviour described in the B -is currently being developed. It thus describes the intended behavior rather +is currently being developed. It thus describes the intended behaviour rather than the current behaviour. It is hoped that it will represent reality in OpenSSL 0.9.5 and later. diff --git a/doc/crypto/BIO_ctrl.pod b/doc/crypto/BIO_ctrl.pod index 5ef27f487e..acc46db8ce 100644 --- a/doc/crypto/BIO_ctrl.pod +++ b/doc/crypto/BIO_ctrl.pod @@ -3,9 +3,9 @@ =head1 NAME BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, -BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, BIO_pending, -BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, BIO_get_info_callback, -BIO_set_info_callback - BIO control operations +BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, +BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, +BIO_get_info_callback, BIO_set_info_callback - BIO control operations =head1 SYNOPSIS @@ -17,6 +17,8 @@ BIO_set_info_callback - BIO control operations long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg); int BIO_reset(BIO *b); + int BIO_seek(BIO *b, int ofs); + int BIO_tell(BIO *b); int BIO_flush(BIO *b); int BIO_eof(BIO *b); int BIO_set_close(BIO *b,long flag); @@ -41,8 +43,14 @@ specific to a particular type of BIO are described in the specific BIOs manual page as well as any special features of the standard calls. -BIO_reset() typically reset a BIO to some initial state, in the case -of file related BIOs for example it rewinds the file pointer. +BIO_reset() typically resets a BIO to some initial state, in the case +of file related BIOs for example it rewinds the file pointer to the +start of the file. + +BIO_seek() resets a file related BIO's file position pointer to B +bytes from start of file. + +BIO_tell() returns the current file position of a file related BIO. BIO_flush() normally writes out any internally buffered data, in some cases it is used to signal EOF and that no more data will be written. @@ -58,14 +66,17 @@ be closed when the BIO is freed. BIO_get_close() returns the BIOs close flag. BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() -return the number of pending characterers in the BIOs read and write buffers. +return the number of pending characters in the BIOs read and write buffers. Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending() return a size_t type and are functions, BIO_pending() and BIO_wpending() are macros which call BIO_ctrl(). =head1 RETURN VALUES -BIO_reset() returns 1 fo success and 0 for failure. +BIO_reset() returns 1 for success and 0 for failure. + +BIO_seek() and BIO_tell() both return the current file position on success +and -1 for failure. BIO_flush() returns 1 for success and 0 or -1 for failure. @@ -91,6 +102,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 recognize the +BIO_ctrl() operation. + =head1 SEE ALSO TBA diff --git a/doc/crypto/BIO_ctrl_get_read_request.pod b/doc/crypto/BIO_ctrl_get_read_request.pod deleted file mode 100644 index 4325fd16f8..0000000000 --- a/doc/crypto/BIO_ctrl_get_read_request.pod +++ /dev/null @@ -1,38 +0,0 @@ -=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 deleted file mode 100644 index 2351191300..0000000000 --- a/doc/crypto/BIO_ctrl_pending.pod +++ /dev/null @@ -1,36 +0,0 @@ -=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_f_cipher.pod b/doc/crypto/BIO_f_cipher.pod index e024865cd4..4182f2c309 100644 --- a/doc/crypto/BIO_f_cipher.pod +++ b/doc/crypto/BIO_f_cipher.pod @@ -38,7 +38,7 @@ is a BIO_ctrl() macro which can be called to determine whether the decryption operation was successful. BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal -BIO cipher context. The retrieved context can be used in conjustion +BIO cipher context. The retrieved context can be used in conjunction with the standard cipher routines to set it up. This is useful when BIO_set_cipher() is not flexible enough for the applications needs. diff --git a/doc/crypto/BIO_f_md.pod b/doc/crypto/BIO_f_md.pod index 0845d2bc2b..c32504dfb1 100644 --- a/doc/crypto/BIO_f_md.pod +++ b/doc/crypto/BIO_f_md.pod @@ -31,7 +31,7 @@ not supported. BIO_reset() reinitializes a digest BIO. BIO_set_md() sets the message digest of BIO B to B: this -must be called to initialise a digest BIO before any data is +must be called to initialize a digest BIO before any data is passed through it. It is a BIO_ctrl() macro. BIO_get_md() places the a pointer to the digest BIOs digest method diff --git a/doc/crypto/BIO_new.pod b/doc/crypto/BIO_new.pod index 53d56b2e6f..2a245fc8de 100644 --- a/doc/crypto/BIO_new.pod +++ b/doc/crypto/BIO_new.pod @@ -40,7 +40,7 @@ BIO_free_all() and BIO_vfree() do not return values. =head1 NOTES Some BIOs (such as memory BIOs) can be used immediately after calling -BIO_new(). Others (such as file BIOs) need some additional initialisation, +BIO_new(). Others (such as file BIOs) need some additional initialization, and frequently a utility function exists to create and initialize such BIOs. If BIO_free() is called on a BIO chain it will only free one BIO resulting diff --git a/doc/crypto/BIO_new_bio_pair.pod b/doc/crypto/BIO_new_bio_pair.pod index c331bd02b8..2256ba9d34 100644 --- a/doc/crypto/BIO_new_bio_pair.pod +++ b/doc/crypto/BIO_new_bio_pair.pod @@ -25,8 +25,8 @@ 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 +separately. This can be of importance, as some SSL-functions like SSL_set_bio() +or SSL_free() call BIO_free() implicitly, so that the peer-BIO is left untouched and must also be BIO_free()'ed. =head1 EXAMPLE @@ -53,7 +53,7 @@ without having to go through the SSL-interface. socket | ... - SSL_free(ssl); /* implicitely frees internal_bio */ + SSL_free(ssl); /* implicitly frees internal_bio */ BIO_free(network_bio); ... diff --git a/doc/crypto/BIO_read.pod b/doc/crypto/BIO_read.pod index 563806c206..b34528104d 100644 --- a/doc/crypto/BIO_read.pod +++ b/doc/crypto/BIO_read.pod @@ -43,8 +43,8 @@ it may merely be an indication that no data is currently available and that the application should retry the operation later. One technique sometimes used with blocking sockets is to use a system call -(such as select(), poll() or eqivalent) to determine when data is available -and then call read() to read the data. The eqivalent with BIOs (that is call +(such as select(), poll() or equivalent) to determine when data is available +and then call read() to read the data. The equivalent with BIOs (that is call select() on the underlying I/O structure and then call BIO_read() to read the data) should B be used because a single call to BIO_read() can cause several reads (and writes in the case of SSL BIOs) on the underlying @@ -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 for details of how to +See L 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 to the chain. =head1 SEE ALSO + L TBA diff --git a/doc/crypto/BIO_s_accept.pod b/doc/crypto/BIO_s_accept.pod index 17fd54a9c6..c49da7fb02 100644 --- a/doc/crypto/BIO_s_accept.pod +++ b/doc/crypto/BIO_s_accept.pod @@ -75,7 +75,9 @@ BIO_set_nbio_accept() sets the accept socket to blocking mode BIO_set_accept_bios() can be used to set a chain of BIOs which will be duplicated and prepended to the chain when an incoming connection is received. This is useful if, for example, a -buffering BIO is required for each connection. +buffering or SSL BIO is required for each connection. The +chain of BIOs must not be freed after this call, they will +be automatically freed when the accept BIO is freed. BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve the current bind mode. If BIO_BIND_NORMAL (the default) is set @@ -100,7 +102,7 @@ BIO is not at then end of a chain it passes I/O calls to the next BIO in the chain. When a connection is established a new socket BIO is created for -the conection and appended to the chain. That is the chain is now +the connection and appended to the chain. That is the chain is now accept->socket. This effectively means that attempting I/O on an initial accept socket will await an incoming connection then perform I/O on it. diff --git a/doc/crypto/BIO_s_bio.pod b/doc/crypto/BIO_s_bio.pod index 2c93f179b9..cf357c669d 100644 --- a/doc/crypto/BIO_s_bio.pod +++ b/doc/crypto/BIO_s_bio.pod @@ -2,10 +2,10 @@ =head1 NAME -BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_set_write_buf_size, -BIO_get_write_buf_size, BIO_new_bio_pair, BIO_get_write_guarantee, -BIO_ctrl_get_write_guarantee, BIO_get_read_request, BIO_ctrl_get_read_request, -BIO_ctrl_reset_read_request - BIO pair BIO +BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_set_shutdown_wr, +BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, +BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, +BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO =head1 SYNOPSIS @@ -16,6 +16,8 @@ BIO_ctrl_reset_read_request - BIO pair BIO #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2) #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL) + #define BIO_set_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL) + #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL) #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL) @@ -60,8 +62,13 @@ BIO_make_bio_pair() joins two separate BIOs into a connected pair. BIO_destroy_pair() destroys the association between two connected BIOs. Freeing up any half of the pair will automatically destroy the association. +BIO_set_shutdown_wr() is used to close down a BIO B. After this call no further +writes on BIO B are allowed (they will return an error). Reads on the other +half of the pair will return any pending data or EOF when all pending data has +been read. + BIO_set_write_buf_size() sets the write buffer size of BIO B to B. -If the size is not initialised a default value is used. This is currently +If the size is not initialized a default value is used. This is currently 17K, sufficient for a maximum size TLS record. BIO_get_write_buf_size() returns the size of the write buffer. @@ -71,25 +78,30 @@ BIO_set_write_buf_size() to create a connected pair of BIOs B, B with write buffer sizes B and B. If either size is zero then the default size is used. -BIO_get_write_guarantee() and BIO_ctrl_get_write_guarentee() return the maximum +BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum length of data that can be currently written to the BIO. Writes larger than this value will return a value from BIO_write() less than the amount requested or if the buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function whereas BIO_get_write_guarantee() is a macro. -BIO_get_read_request() and BIO_ctrl_get_read_request() return the amount of data -requested (or the buffer size if it is less) if the last read failed due to an -empty buffer. This can be used to determine how much data should be written to the -other half of the pair so the next read will succeed: this is most useful in TLS/SSL -applications where the amount of data read is usually meaningful rather than just -a buffer size. After a successful read this call will return zero. +BIO_get_read_request() and BIO_ctrl_get_read_request() return the +amount of data requested, or the buffer size if it is less, if the +last read attempt at the other half of the BIO pair failed due to an +empty buffer. This can be used to determine how much data should be +written to the BIO so the next read will succeed: this is most useful +in TLS/SSL applications where the amount of data read is usually +meaningful rather than just a buffer size. After a successful read +this call will return zero. It also will return zero once new data +has been written satisfying the read request or part of it. +Note that BIO_get_read_request() never returns an amount larger +than that returned by BIO_get_write_guarantee(). BIO_ctrl_reset_read_request() can also be used to reset the value returned by BIO_get_read_request() to zero. =head1 NOTES -Both halves of a BIO pair should be freed. That is even if one half is implicity +Both halves of a BIO pair should be freed. That is even if one half is implicit freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed. When used in bidirectional applications (such as TLS/SSL) care should be taken to @@ -103,7 +115,7 @@ BIO_write() and a response read with BIO_read(), this can occur during an TLS/SSL handshake for example. BIO_write() will succeed and place data in the write buffer. BIO_read() will initially fail and BIO_should_read() will be true. If the application then waits for data to be available on the underlying transport -before flusing the write buffer it will never succeed because the request was +before flushing the write buffer it will never succeed because the request was never sent! =head1 EXAMPLE diff --git a/doc/crypto/BIO_s_connect.pod b/doc/crypto/BIO_s_connect.pod index 65723a70a4..fe1aa679d4 100644 --- a/doc/crypto/BIO_s_connect.pod +++ b/doc/crypto/BIO_s_connect.pod @@ -66,13 +66,13 @@ fails a standard table of port names will be used. Currently the list is http, telnet, socks, https, ssl, ftp, gopher and wais. BIO_set_conn_ip() sets the IP address to B using binary form, -that is four bytes specifying the IP address in big endian form. +that is four bytes specifying the IP address in big-endian form. BIO_set_conn_int_port() sets the port using B. B should be of type (int *). BIO_get_conn_hostname() returns the hostname of the connect BIO or -NULL if the BIO is initialised but no hostname is set. +NULL if the BIO is initialized but no hostname is set. This return value is an internal pointer which should not be modified. BIO_get_conn_port() returns the port as a string. @@ -120,7 +120,7 @@ It addition to BIO_should_read() and BIO_should_write() it is also possible for BIO_should_io_special() to be true during the initial connection process with the reason BIO_RR_CONNECT. If this is returned then this is an indication that a connection attempt would block, -the application should then take appropiate action to wait until +the application should then take appropriate action to wait until the underlying socket has connected and retry the call. =head1 RETURN VALUES @@ -128,7 +128,7 @@ the underlying socket has connected and retry the call. BIO_s_connect() returns the connect BIO method. BIO_get_fd() returns the socket or -1 if the BIO has not -been initialised. +been initialized. BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and BIO_set_conn_int_port() always return 1. diff --git a/doc/crypto/BIO_s_fd.pod b/doc/crypto/BIO_s_fd.pod index da08ba1023..61789fd2c1 100644 --- a/doc/crypto/BIO_s_fd.pod +++ b/doc/crypto/BIO_s_fd.pod @@ -20,15 +20,6 @@ BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO BIO_s_fd() returns the file descriptor BIO method. This is a wrapper round the platforms file descriptor routines such as read() and write(). -BIO_read() and BIO_write() read or write the underlying descriptor. -BIO_puts() is supported but BIO_gets() is not. - -If the close flag is set then then close() is called on the underlying -file descriptor when the BIO is freed. - -BIO_reset() attempts to change the file pointer to the start of file -using lseek(fd, 0, 0). - BIO_set_fd() sets the file descriptor of BIO B to B and the close flag to B. @@ -36,11 +27,20 @@ BIO_get_fd() places the file descriptor in B if it is not NULL, it also returns the file descriptor. If B is not NULL it should be of type (int *). -BIO_new_fd() returns a file desciptor BIO using B and B. +BIO_new_fd() returns a file descriptor BIO using B and B. =head1 NOTES -The behaviour of BIO_read() and BIO_write() depends on the behaviour of the +If the close flag is set then then close() is called on the underlying +file descriptor when the BIO is freed. + +BIO_reset() attempts to change the file pointer to the start of file +using lseek(fd, 0, 0). + +BIO_read() and BIO_write() read or write the underlying descriptor. +BIO_puts() is supported but BIO_gets() is not. + +The behaviour of BIO_read() and BIO_write() depends on the behavior of the platforms read() and write() calls on the descriptor. If the underlying file descriptor is in a non blocking mode then the BIO will behave in the manner described in the L and L @@ -53,15 +53,10 @@ instead. BIO_s_fd() returns the file descriptor BIO method. -BIO_reset() returns zero for success and -1 if an error occurred. -BIO_seek() and BIO_tell() return the current file position or -1 -is an error occurred. These values reflect the underlying lseek() -behaviour. - BIO_set_fd() always returns 1. BIO_get_fd() returns the file descriptor or -1 if the BIO has not -been initialised. +been initialized. BIO_new_fd() returns the newly allocated BIO or NULL is an error occurred. @@ -77,4 +72,8 @@ This is a file descriptor BIO version of "Hello World": =head1 SEE ALSO -L, L, TBA +L, L, +L, L, +L, L, +L, L, +L, L diff --git a/doc/crypto/BIO_s_file.pod b/doc/crypto/BIO_s_file.pod index 10fe4933c7..166734b0bc 100644 --- a/doc/crypto/BIO_s_file.pod +++ b/doc/crypto/BIO_s_file.pod @@ -28,20 +28,6 @@ BIO_s_file() returns the BIO file method. As its name implies it is a wrapper round the stdio FILE structure and it is a source/sink BIO. -Calls to BIO_read() and BIO_write() read and write data to the -underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs. - -BIO_flush() on a file BIO calls the fflush() function on the wrapped -stream. - -BIO_reset() on a file BIO calls fseek() to reset the position indicator -to the start of the file. - -BIO_eof() calls feof(). - -Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO -is freed. - BIO_new_file() creates a new file BIO with mode B the meaning of B is the same as the stdio function fopen(). The BIO_CLOSE flag is set on the returned BIO. @@ -62,6 +48,20 @@ reading, writing, append or read write respectively. =head1 NOTES +Calls to BIO_read() and BIO_write() read and write data to the +underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs. + +BIO_flush() on a file BIO calls the fflush() function on the wrapped +stream. + +BIO_reset() on a file BIO calls fseek() to reset the position indicator +to the start of the file. + +BIO_eof() calls feof(). + +Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO +is freed. + When wrapping stdout, stdin or stderr the underlying stream should not normally be closed so the BIO_NOCLOSE flag should be set. @@ -116,4 +116,9 @@ BIO_rw_filename() return 1 for success or 0 for failure. =head1 SEE ALSO -L, L, TBA +L, L, +L, L, +L, +L, L, +L, L, +L, L diff --git a/doc/crypto/BIO_s_mem.pod b/doc/crypto/BIO_s_mem.pod index 0c5f58ed1b..19648acfae 100644 --- a/doc/crypto/BIO_s_mem.pod +++ b/doc/crypto/BIO_s_mem.pod @@ -87,9 +87,7 @@ There should be a way to "rewind" a read write BIO without destroying its contents. The copying operation should not occur after every small read of a large BIO -to improve efficieny. - -There shoy +to improve efficiency. =head1 EXAMPLE diff --git a/doc/crypto/BIO_s_socket.pod b/doc/crypto/BIO_s_socket.pod index ec450e11f1..253185185c 100644 --- a/doc/crypto/BIO_s_socket.pod +++ b/doc/crypto/BIO_s_socket.pod @@ -51,7 +51,7 @@ BIO_s_socket() returns the socket BIO method. BIO_set_fd() always returns 1. BIO_get_fd() returns the socket or -1 if the BIO has not been -initialised. +initialized. BIO_new_socket() returns the newly allocated BIO or NULL is an error occurred. diff --git a/doc/crypto/BIO_seek.pod b/doc/crypto/BIO_seek.pod deleted file mode 100644 index 3f92d5cbd5..0000000000 --- a/doc/crypto/BIO_seek.pod +++ /dev/null @@ -1,30 +0,0 @@ -=pod - -=head1 NAME - -BIO_seek, BIO_tell - file BIO operations - -=head1 SYNOPSIS - - #include - - #define BIO_seek(b,ofs) (int)BIO_ctrl(b,BIO_C_FILE_SEEK,ofs,NULL) - #define BIO_tell(b) (int)BIO_ctrl(b,BIO_C_FILE_TELL,0,NULL) - -=head1 DESCRIPTION - -BIO_seek() sets the file position pointer to B bytes from start of file. - -BIO_tell() returns the current file position. - -=head1 RETURN VALUES - -BIO_seek() returns the same value as the underlying fseek() function: -0 for success or -1 for failure. - -BIO_tell() returns the current file position. - -=head1 SEE ALSO - -TBA - diff --git a/doc/crypto/bio.pod b/doc/crypto/bio.pod index 987ec838fb..24f61dfb56 100644 --- a/doc/crypto/bio.pod +++ b/doc/crypto/bio.pod @@ -39,4 +39,16 @@ BIO). =head1 SEE ALSO -TBA +L, +L, +L, L, +L, L, +L, L, +L, +L, L, +L, L, +L, L, +L, L, +L, L, +L, +L diff --git a/doc/crypto/threads.pod b/doc/crypto/threads.pod index bcaa94d1bb..7fa18aa443 100644 --- a/doc/crypto/threads.pod +++ b/doc/crypto/threads.pod @@ -106,7 +106,7 @@ CRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield describing what should be done with the lock. n is the number of the lock as returned from CRYPTO_get_new_dynlockid(). mode can be combined from the following values. These values are pairwise exclusive, with -undefined behavior if misused (for example, CRYPTO_READ and CRYPTO_WRITE +undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE should not be used together): CRYPTO_LOCK 0x01 diff --git a/doc/ssl/SSL_SESSION_free.pod b/doc/ssl/SSL_SESSION_free.pod index 2ec7544cac..5e104d5f2f 100644 --- a/doc/ssl/SSL_SESSION_free.pod +++ b/doc/ssl/SSL_SESSION_free.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_SESSION_free - Free up an allocated SSL_SESSION structure +SSL_SESSION_free - free an allocated SSL_SESSION structure =head1 SYNOPSIS @@ -13,7 +13,7 @@ SSL_SESSION_free - Free up an allocated SSL_SESSION structure =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 +the B structure pointed to by B and frees up the allocated memory, if the the reference count has reached 0. =head1 RETURN VALUES diff --git a/doc/ssl/SSL_accept.pod b/doc/ssl/SSL_accept.pod index d21a391cb8..fc6a57b5da 100644 --- a/doc/ssl/SSL_accept.pod +++ b/doc/ssl/SSL_accept.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_accept - Wait for a TLS client to initiate a TLS handshake +SSL_accept - wait for a TLS/SSL client to initiate a TLS/SSL handshake =head1 SYNOPSIS @@ -12,22 +12,22 @@ SSL_accept - Wait for a TLS client to initiate a TLS handshake =head1 DESCRIPTION -SSL_accept() waits for a TLS client to initiate the TLS handshake. +SSL_accept() waits for a TLS/SSL client to initiate the TLS/SSL 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() +If the underlying BIO is B, SSL_accept() will only return once the +handshake has been finished or an error occurred, except for SGC (Server +Gated Cryptography). For SGC, SSL_accept() may return with -1, but +SSL_get_error() will yield B and SSL_accept() should be called again. -If the underlying BIO is B, SSL_accept() will also return, +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 +return value of SSL_accept() will yield B or +B. 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 @@ -42,20 +42,20 @@ The following return values can occur: =item 1 -The TLS handshake was successfully completed, a TLS connection has been +The TLS/SSL handshake was successfully completed, a TLS/SSL 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 +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL 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 +The TLS/SSL handshake was not successful because a fatal error occurred either +at the protocol level or a connection failure occurred. The shutdown was +not clean. It can also occur 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. diff --git a/doc/ssl/SSL_clear.pod b/doc/ssl/SSL_clear.pod index c68938b4bc..1d80b45f0c 100644 --- a/doc/ssl/SSL_clear.pod +++ b/doc/ssl/SSL_clear.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_clear - Reset SSL to allow another connection +SSL_clear - reset SSL object to allow another connection =head1 SYNOPSIS @@ -12,9 +12,9 @@ SSL_clear - Reset SSL to allow another connection =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. +Reset B to allow another connection. All settings (method, ciphers, +BIOs) are kept. A completely negotiated B is not freed but left +untouched for the underlying B. =head1 RETURN VALUES @@ -29,7 +29,7 @@ find out the reason. =item 1 -The SSL_clear() operation was successfull. +The SSL_clear() operation was successful. =back diff --git a/doc/ssl/SSL_connect.pod b/doc/ssl/SSL_connect.pod index 269edd0e70..7123bf3257 100644 --- a/doc/ssl/SSL_connect.pod +++ b/doc/ssl/SSL_connect.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_connect - Initiate the TLS handshake with an TLS server +SSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server =head1 SYNOPSIS @@ -12,19 +12,19 @@ SSL_connect - Initiate the TLS handshake with an TLS server =head1 DESCRIPTION -SSL_connect() initiates the TLS handshake with a server. The communication +SSL_connect() initiates the TLS/SSL 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 only return once the +handshake has been finished or an error occurred. -If the underlying BIO is B, SSL_connect() will also return, +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 +return value of SSL_connect() will yield B or +B. 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 @@ -39,20 +39,20 @@ The following return values can occur: =item 1 -The TLS handshake was successfully completed, a TLS connection has been +The TLS/SSL handshake was successfully completed, a TLS/SSL 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 +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL 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 +The TLS/SSL handshake was not successful, because a fatal error occurred either +at the protocol level or a connection failure occurred. The shutdown was +not clean. It can also occur 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. diff --git a/doc/ssl/SSL_free.pod b/doc/ssl/SSL_free.pod index 3d01234a85..3bbde4273c 100644 --- a/doc/ssl/SSL_free.pod +++ b/doc/ssl/SSL_free.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_free - Free up an allocated SSL structure +SSL_free - free an allocated SSL structure =head1 SYNOPSIS @@ -12,13 +12,13 @@ SSL_free - Free up an allocated SSL structure =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 +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. +cipher lists specially created for this B, the B. 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. diff --git a/doc/ssl/SSL_get_error.pod b/doc/ssl/SSL_get_error.pod index 7851830fc5..d85b564258 100644 --- a/doc/ssl/SSL_get_error.pod +++ b/doc/ssl/SSL_get_error.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_get_error - obtain result code for SSL I/O operation +SSL_get_error - obtain result code for TLS/SSL I/O operation =head1 SYNOPSIS @@ -15,14 +15,14 @@ SSL_get_error - obtain result code for SSL I/O operation SSL_get_error() returns a result code (suitable for the C "switch" statement) for a preceding call to SSL_connect(), SSL_accept(), SSL_read(), or SSL_write() on B. The value returned by that -SSL I/O function must be passed to SSL_get_error() in parameter +TLS/SSL I/O function must be passed to SSL_get_error() in parameter B. In addition to B and B, SSL_get_error() inspects the current thread's OpenSSL error queue. Thus, SSL_get_error() must be -used in the same thread that performed the SSL I/O operation, and no +used in the same thread that performed the TLS/SSL I/O operation, and no other OpenSSL function calls should appear in between. The current -thread's error queue must be empty before the SSL I/O operation is +thread's error queue must be empty before the TLS/SSL I/O operation is attempted, or SSL_get_error() will not work reliably. =head1 RETURN VALUES @@ -33,12 +33,12 @@ The following return values can currently occur: =item SSL_ERROR_NONE -The SSL I/O operation completed. This result code is returned +The TLS/SSL I/O operation completed. This result code is returned if and only if B 0>. =item SSL_ERROR_ZERO_RETURN -The SSL connection has been closed. If the protocol version is SSL 3.0 +The TLS/SSL connection has been closed. If the protocol version is SSL 3.0 or TLS 1.0, this result code is returned only if a closure alert has occurred in the protocol, i.e. if the connection has been closed cleanly. Note that in this case B @@ -47,15 +47,15 @@ has been closed. =item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE -The operation did not complete; the same SSL I/O function should be +The operation did not complete; the same TLS/SSL I/O function should be called again later. There will be protocol progress if, by then, the underlying B has data available for reading (if the result code is B) or allows writing data (B). For socket Bs (e.g. when SSL_set_fd() was used) this means that select() or poll() on the underlying socket can be used to find out -when the SSL I/O function should be retried. +when the TLS/SSL I/O function should be retried. -Caveat: Any SSL I/O function can lead to either of +Caveat: Any TLS/SSL I/O function can lead to either of B and B, i.e. SSL_read() may want to write data and SSL_write() may want to read data. @@ -63,7 +63,7 @@ may want to write data and SSL_write() may want to read data. The operation did not complete because an application callback set by SSL_CTX_set_client_cert_cb() has asked to be called again. -The SSL I/O function should be called again later. +The TLS/SSL I/O function should be called again later. Details depend on the application. =item SSL_ERROR_SYSCALL diff --git a/doc/ssl/SSL_get_fd.pod b/doc/ssl/SSL_get_fd.pod index 0ed21d5f15..a3f7625931 100644 --- a/doc/ssl/SSL_get_fd.pod +++ b/doc/ssl/SSL_get_fd.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_get_fd - Get file descriptor linked to an SSL +SSL_get_fd - get file descriptor linked to an SSL object =head1 SYNOPSIS diff --git a/doc/ssl/SSL_get_rbio.pod b/doc/ssl/SSL_get_rbio.pod index 40a5f12e71..3d98233cac 100644 --- a/doc/ssl/SSL_get_rbio.pod +++ b/doc/ssl/SSL_get_rbio.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_get_rbio - Get BIO linked to an SSL +SSL_get_rbio - get BIO linked to an SSL object =head1 SYNOPSIS @@ -25,7 +25,7 @@ The following return values can occur: =item NULL -No BIO was connected to the SSL +No BIO was connected to the SSL object =item Any other pointer diff --git a/doc/ssl/SSL_get_session.pod b/doc/ssl/SSL_get_session.pod index 0b3f50af42..aff41fb9cf 100644 --- a/doc/ssl/SSL_get_session.pod +++ b/doc/ssl/SSL_get_session.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_get_session - Retrieve SSL session data +SSL_get_session - retrieve TLS/SSL session data =head1 SYNOPSIS @@ -14,15 +14,15 @@ SSL_get_session - Retrieve SSL session data =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 +SSL_get_session() returns a pointer to the B actually used in +B. The reference count of the B 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. +count of the B is incremented by one. =head1 RETURN VALUES diff --git a/doc/ssl/SSL_new.pod b/doc/ssl/SSL_new.pod index a393c94c02..8e8638fa95 100644 --- a/doc/ssl/SSL_new.pod +++ b/doc/ssl/SSL_new.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_new - Create a new SSL structure for a connection +SSL_new - create a new SSL structure for a connection =head1 SYNOPSIS @@ -12,10 +12,10 @@ SSL_new - Create a new SSL structure for a connection =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. +SSL_new() creates a new B structure which is needed to hold the +data for a TLS/SSL connection. The new structure inherits the settings +of the underlying context B: connection method (SSLv2/v3/TLSv1), +options, verification settings, timeout settings. =head1 RETURN VALUES @@ -25,10 +25,10 @@ The following return values can occur: =item NULL -The creation of a new SSL failed. Check the error stack to find out the -reason. +The creation of a new SSL structure failed. Check the error stack to +find out the reason. -=item Pointer to an SSL +=item Pointer to an SSL structure The return value points to an allocated SSL structure. diff --git a/doc/ssl/SSL_read.pod b/doc/ssl/SSL_read.pod index 9df51030c5..3b082a7c90 100644 --- a/doc/ssl/SSL_read.pod +++ b/doc/ssl/SSL_read.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_read - Read bytes from a TLS connection. +SSL_read - read bytes from a TLS/SSL connection. =head1 SYNOPSIS @@ -13,20 +13,20 @@ SSL_read - Read bytes from a TLS connection. =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 +buffer B. If necessary, SSL_read() will negotiate a TLS/SSL session, if +not already explicitly 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. +read operation has been finished or an error occurred. -If the underlying BIO is B, SSL_read() will also return, +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 +return value of SSL_read() will yield B or +B. 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 @@ -42,18 +42,18 @@ The following return values can occur: =item E0 -The read operation was successfull, the return value is the number of -bytes actually read from the TLS connection. +The read operation was successful; the return value is the number of +bytes actually read from the TLS/SSL connection. =item 0 -The read operation was not successfull, probably because no data was +The read operation was not successful, probably because no data was available. Call SSL_get_error() with the return value B to find out, -whether an error occured. +whether an error occurred. =item -1 -The read operation was not successfull, because either an error occured +The read operation was not successful, because either an error occurred or action must be taken by the calling process. Call SSL_get_error() with the return value B to find out the reason. diff --git a/doc/ssl/SSL_set_bio.pod b/doc/ssl/SSL_set_bio.pod index 24fa77e71d..67c9756d3f 100644 --- a/doc/ssl/SSL_set_bio.pod +++ b/doc/ssl/SSL_set_bio.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_set_bio - Connect the SSL with a BIO +SSL_set_bio - connect the SSL object with a BIO =head1 SYNOPSIS @@ -13,7 +13,7 @@ SSL_set_bio - Connect the SSL with a BIO =head1 DESCRIPTION SSL_set_bio() connects the BIOs B and B for the read and write -operations of the TLS (encrypted) side of B. +operations of the TLS/SSL (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. @@ -29,6 +29,6 @@ SSL_set_bio() cannot fail. L, L, L, -L, L , L +L, L, L =cut diff --git a/doc/ssl/SSL_set_fd.pod b/doc/ssl/SSL_set_fd.pod index 076791e17b..70291128fc 100644 --- a/doc/ssl/SSL_set_fd.pod +++ b/doc/ssl/SSL_set_fd.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_set_fd - Connect the SSL with a file descriptor +SSL_set_fd - connect the SSL object with a file descriptor =head1 SYNOPSIS @@ -15,7 +15,7 @@ SSL_set_fd - Connect the SSL with a file descriptor =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 +for the TLS/SSL (encrypted) side of B. B will typically be the socket file descriptor of a network connection. When performing the operation, a B is automatically created to @@ -26,8 +26,8 @@ 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. +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 independently. =head1 RETURN VALUES diff --git a/doc/ssl/SSL_set_session.pod b/doc/ssl/SSL_set_session.pod index b1162ba61a..447f5d4acc 100644 --- a/doc/ssl/SSL_set_session.pod +++ b/doc/ssl/SSL_set_session.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_set_session - Set an SSL session to be used during SSL connect +SSL_set_session - set a TLS/SSL session to be used during TLS/SSL connect =head1 SYNOPSIS @@ -12,15 +12,15 @@ SSL_set_session - Set an SSL session to be used during SSL connect =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. +SSL_set_session() sets B to be used when the TLS/SSL connection +is to be established. SSL_set_session() is only useful for TLS/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. +a connection), SSL_SESSION_free() will be called for that session. =head1 RETURN VALUES @@ -30,7 +30,7 @@ The following return values can occur: =item 0 -The operation failed, check the error stack to find out the reason. +The operation failed; check the error stack to find out the reason. =item 1 diff --git a/doc/ssl/SSL_shutdown.pod b/doc/ssl/SSL_shutdown.pod index be1166b596..20e273bd4d 100644 --- a/doc/ssl/SSL_shutdown.pod +++ b/doc/ssl/SSL_shutdown.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_shutdown - Shut down a TLS connection +SSL_shutdown - shut down a TLS/SSL connection =head1 SYNOPSIS @@ -12,18 +12,18 @@ SSL_shutdown - Shut down a TLS connection =head1 DESCRIPTION -SSL_shutdown() shuts down an active TLS connection. It sends the shutdown +SSL_shutdown() shuts down an active TLS/SSL 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 only return once the +handshake has been finished or an error occurred. -If the underlying BIO is B, SSL_shutdown() will also return, +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 +return value of SSL_shutdown() will yield B or +B. 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 @@ -42,13 +42,13 @@ The shutdown was successfully completed. =item 0 -The shutdown was not successfull. Call SSL_get_error() with the return +The shutdown was not successful. 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 +The shutdown was not successful because a fatal error occurred either +at the protocol level or a connection failure occurred. It can also occur 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. diff --git a/doc/ssl/SSL_write.pod b/doc/ssl/SSL_write.pod index 9b433c0e2d..b086258e82 100644 --- a/doc/ssl/SSL_write.pod +++ b/doc/ssl/SSL_write.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_read - Write bytes to a TLS connection. +SSL_read - write bytes to a TLS/SSL connection. =head1 SYNOPSIS @@ -13,20 +13,20 @@ SSL_read - Write bytes to a TLS connection. =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 +B. If necessary, SSL_write() will negotiate a TLS/SSL session, if +not already explicitly 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. +write operation has been finished or an error occurred. 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 +return value of SSL_write() will yield B or +B. 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 @@ -42,17 +42,17 @@ The following return values can occur: =item E0 -The write operation was successfull, the return value is the number of -bytes actually written to the TLS connection. +The write operation was successful, the return value is the number of +bytes actually written to the TLS/SSL 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. +The write operation was not successful. Call SSL_get_error() with the return +value B to find out, whether an error occurred. =item -1 -The read operation was not successfull, because either an error occured +The read operation was not successful, because either an error occurred or action must be taken by the calling process. Call SSL_get_error() with the return value B to find out the reason. diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index 362c414bb8..41d6114649 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -83,7 +83,7 @@ B structures which are later created for the connections. =item B (SSL Session) -This is a structure containing the current SSL session details for a +This is a structure containing the current TLS/SSL session details for a connection: Bs, client and server certificates, keys, etc. =item B (SSL Connection) @@ -624,7 +624,16 @@ connection defined in the B structure. =head1 SEE ALSO L, L, -L +L, L, +L, L, +L, L, +L, +L, L, +L, L, +L, +L, +L, L, +L =head1 HISTORY -- 2.25.1