diff --git a/doc/crypto/BIO_ctrl.pod b/doc/crypto/BIO_ctrl.pod index aed2095925f1c644f52495235e6de19e640c90e3..421a3ac1cbd75a8a69aa3c759d9777db9cfa14ac 100644 --- a/doc/crypto/BIO_ctrl.pod +++ b/doc/crypto/BIO_ctrl.pod @@ -58,14 +58,14 @@ 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_flush() returns 1 for success and 0 or -1 for failure. @@ -97,7 +97,7 @@ This often means there is no need to locate the required BIO for a particular operation, it can be called on a chain and it will be automatically passed to the relevant BIO. -Source/sink BIOs will return an error if the do not recognise the +Source/sink BIOs will return an error if the do not recognize the BIO_ctrl() operation. =head1 SEE ALSO diff --git a/doc/crypto/BIO_f_cipher.pod b/doc/crypto/BIO_f_cipher.pod index e024865cd47bd2c47fa65cdfd368a868075fd6be..4182f2c30903181405934e5f0df6f0f0765b6cbe 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 0845d2bc2bf4f611f18c9bfd66b028c126f35b18..ebca9440654bc20c2e191417c8d108cf6890bc7b 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 @@ -127,7 +127,7 @@ outputs them. This could be used with the examples above. =head1 BUGS -The lack of support for BIO_puts() and the non standard behaviour of +The lack of support for BIO_puts() and the non standard behavior of BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets() and BIO_puts() should be passed to the next BIO in the chain and digest the data passed through and that digests should be retrieved using a diff --git a/doc/crypto/BIO_f_ssl.pod b/doc/crypto/BIO_f_ssl.pod index 4ae440042737555cf36d40d6d7a6ddf8f635c9ee..122deb42cb67c3b57d8c5aa28e48b380dc3098e7 100644 --- a/doc/crypto/BIO_f_ssl.pod +++ b/doc/crypto/BIO_f_ssl.pod @@ -33,7 +33,7 @@ BIO_ssl_shutdown - SSL BIO =head1 DESCRIPTION BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which -is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to +is a wrapper round the OpenSSL SSL routines adding a BIO "flavor" to SSL I/O. I/O performed on an SSL BIO communicates using the SSL protocol with @@ -65,7 +65,7 @@ the SSL session is automatically renegotiated. B must be at least 512 bytes. BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to -B. When the renegotiate timeout elapses the sesssion is +B. When the renegotiate timeout elapses the session is automatically renegotiated. BIO_get_num_renegotiates() returns the total number of session @@ -100,7 +100,7 @@ renegotiation takes place during a BIO_read() operation, one case where this happens is when SGC or step up occurs. In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be -set to disable this behaviour. That is when this flag is set +set to disable this behavior. That is when this flag is set an SSL BIO using a blocking transport will never request a retry. diff --git a/doc/crypto/BIO_new.pod b/doc/crypto/BIO_new.pod index 53d56b2e6fadcb977979af3d5d0f91d5faa2a115..2a245fc8de83e962aec0153cf22a872199144c66 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 c331bd02b8441c33350d983db19200f944bcbe9a..2256ba9d341077d7d03aaf5e9e4431da4361af1f 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 d9311708abfc46fc1b3ac01014446fb33150bd4d..b34528104ddf248813b68c666111f0316986aefc 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 diff --git a/doc/crypto/BIO_s_accept.pod b/doc/crypto/BIO_s_accept.pod index 17fd54a9c6b4ff7ad7f7c702012c5a5f66c3270f..ddb1f9a2b02da8292fb7804cbdadf46ef15a2879 100644 --- a/doc/crypto/BIO_s_accept.pod +++ b/doc/crypto/BIO_s_accept.pod @@ -100,7 +100,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 2c93f179b9e88905d96948ae6ec5d0d81d365224..7a3b2db141461cee9168166e8b07409d6220302f 100644 --- a/doc/crypto/BIO_s_bio.pod +++ b/doc/crypto/BIO_s_bio.pod @@ -61,7 +61,7 @@ BIO_destroy_pair() destroys the association between two connected BIOs. Freeing up any half of the pair will automatically destroy the association. 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,7 +71,7 @@ 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 @@ -89,7 +89,7 @@ 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 +103,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 65723a70a458a886ba372379bd70a61025e5bb3b..fe1aa679d441b7b4e81f8a04854fe94fd92b6b1d 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 da08ba10234076d5d59014f294ba4d9892f07249..e0ca2eca9435860e78c87695b11ef5c45ddb574b 100644 --- a/doc/crypto/BIO_s_fd.pod +++ b/doc/crypto/BIO_s_fd.pod @@ -36,11 +36,11 @@ 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 +The behavior 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 @@ -56,12 +56,12 @@ 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. +behavior. 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. diff --git a/doc/crypto/BIO_s_file.pod b/doc/crypto/BIO_s_file.pod index 10fe4933c72343a63821df8f08e693d2f0077730..672dc2f48de07ef4ce7e1d83cf2857fa0ffb150c 100644 --- a/doc/crypto/BIO_s_file.pod +++ b/doc/crypto/BIO_s_file.pod @@ -66,7 +66,7 @@ When wrapping stdout, stdin or stderr the underlying stream should not normally be closed so the BIO_NOCLOSE flag should be set. Because the file BIO calls the underlying stdio functions any quirks -in stdio behaviour will be mirrored by the corresponding BIO. +in stdio behavior will be mirrored by the corresponding BIO. =head1 EXAMPLES diff --git a/doc/crypto/BIO_s_mem.pod b/doc/crypto/BIO_s_mem.pod index 0c5f58ed1bcce17883c95da4b60537a3bad3de79..32089325886ecae39913249bc558a755397135a1 100644 --- a/doc/crypto/BIO_s_mem.pod +++ b/doc/crypto/BIO_s_mem.pod @@ -43,7 +43,7 @@ BIO_eof() is true if no data is in the BIO. BIO_ctrl_pending() returns the number of bytes currently stored. -BIO_set_mem_eof_return() sets the behaviour of memory BIO B when it is +BIO_set_mem_eof_return() sets the behavior of memory BIO B when it is empty. If the B is zero then an empty memory BIO will return EOF (that is it will return zero and BIO_should_retry(b) will be false. If B is non zero then it will return B when it is empty and it will set the read retry @@ -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 ec450e11f1b7fd98e57027da37e734d300bba347..253185185c7f1b87e7ee683507c48cddd0eec3bc 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_should_retry.pod b/doc/crypto/BIO_should_retry.pod index 539c3912728caebc5e77bfcadf583e52f061cc92..cd7adcd425c33358f05c0be35a1a5c66fe95620f 100644 --- a/doc/crypto/BIO_should_retry.pod +++ b/doc/crypto/BIO_should_retry.pod @@ -97,7 +97,7 @@ the performance may be poor if SSL BIOs are present because long delays can occur during the initial handshake process. It is possible for a BIO to block indefinitely if the underlying I/O -structure cannot process or return any data. This depends on the behaviour of +structure cannot process or return any data. This depends on the behavior of the platforms I/O functions. This is often not desirable: one solution is to use non blocking I/O and use a timeout on the select() (or equivalent) call. diff --git a/doc/ssl/SSL_SESSION_free.pod b/doc/ssl/SSL_SESSION_free.pod index 2ec7544cac1638673ebcefe3bb649f946f1bc4a9..5e104d5f2f5792a4168dd616f479151750d56874 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 d21a391cb87e27b4c46fc66e589aa1832238f9ce..303cf2468056e350f4da3455f5880214d6801832 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 +B by setting an underlying B. The behavior 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 c68938b4bce1db588e2ce49c85bd1951d61eb908..1d80b45f0c3c27d82b22876ea2f2ab5a26c6a60d 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 269edd0e709e3efb7cd15354f78f753cf3d99ffc..a5027717cf084e5686f072135b97c074573736a3 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 @@ -14,17 +14,17 @@ SSL_connect - Initiate the TLS handshake with an TLS server 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 +underlying B. The behavior 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 3d01234a8579dc4831e771b3e9e93aed55675e0b..3bbde4273c9bca1c76fb0340ee79d9db8ae1e3d7 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 7851830fc581847c2a101a766a265a0c25e09bd1..8e76e1e69efe6e4f603d248e7ca2f749d315960a 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,13 +47,13 @@ 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 B and B, i.e. SSL_read() diff --git a/doc/ssl/SSL_get_fd.pod b/doc/ssl/SSL_get_fd.pod index 0ed21d5f15fcdfcdf583cb30db44d2892dbd3ab5..a3f76259316f554924b1191646f1525849d42e80 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 40a5f12e71d3e82c2cf5e0cf8c1f89b812a3dc4c..3d98233cacee7193ace8e453d81a950a1f4fe747 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 0b3f50af4277469f620e5fe63b94aa1624b0cea4..aff41fb9cf624def4069f9cd2616aeb64aea9ec5 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 a393c94c02e6e2d6fcd95430593f1a6bb4485035..8e8638fa9561091f7a6f1918135a5a940ff90d24 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 9df51030c58846d3ceb8984b833b622ae9a7c4fc..a1fc0fb3563e123047249a578e4caf6f91b15f36 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 +the SSL_read() operation. The behavior 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 24fa77e71d3142561b514ab9d49016ae13de603a..296aa6d7e27241cbc683a934aa837a7a954f474c 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,10 +13,10 @@ 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. +The SSL engine inherits the behavior of B and B, respectively. +If a BIO is non-blocking, the B will also have non-blocking behavior. If there was already a BIO connected to B, BIO_free() will be called (for both the reading and writing side, if different). @@ -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 076791e17ba06d4b72d135fd230c19fbb29a38f5..f6d9b7a1dcc15e70b841990f1fa351abfbc05b47 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,19 +15,19 @@ 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 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. +inherit the behavior of B. If B is non-blocking, the B will +also have non-blocking behavior. 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 b1162ba61a9c91b22aa31726eda07006ec63a8ea..447f5d4acc6d0d3202a2b3c0042dbdca366d0757 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 be1166b596078ae8b56735fb9e01f4aa7675e430..f287aad9ce7a1590798c211cc958f01056758a6e 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 -alert to the peer. The behaviour of SSL_shutdown() depends on the underlying +SSL_shutdown() shuts down an active TLS/SSL connection. It sends the shutdown +alert to the peer. The behavior 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 9b433c0e2d558acfa4ab58ea075d9406acb9cae1..4db85473d9a9c552848f07f5c4616d8f3b9f1bb8 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 +the SSL_write() operation. The behavior 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.