Merge from main trunk.
This commit is contained in:
Richard Levitte
parent
90ac586317
commit
8de7587e02
@ -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)
|
||||
|
||||
@ -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<TRUST SETTINGS>
|
||||
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.
|
||||
|
||||
|
||||
@ -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<ofs>
|
||||
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
|
||||
|
||||
@ -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 <openssl/bio.h>
|
||||
|
||||
size_t BIO_ctrl_get_read_request(BIO *bio);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_ctrl_get_read_request() returns the number of bytes that were last
|
||||
requested from B<bio> by a BIO_read() operation. This is useful e.g. for
|
||||
BIO pairs, so that the application knows how much bytes to supply to B<bio>.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
When B<bio> is NULL, the OpenSSL library calls assert().
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
The following return values can occur:
|
||||
|
||||
=over 4
|
||||
|
||||
=item E<gt>=0
|
||||
|
||||
The number of bytes requested.
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<bio(3)|bio(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>,
|
||||
L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)>
|
||||
@ -1,36 +0,0 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_ctrl_pending - Find out how much bytes are buffered in a BIO
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
size_t BIO_ctrl_pending(BIO *bio);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_ctrl_pending() returns the number of bytes buffered in a BIO.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
When B<bio> is NULL, the OpenSSL library calls assert().
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
The following return values can occur:
|
||||
|
||||
=over 4
|
||||
|
||||
=item E<gt>=0
|
||||
|
||||
The number of bytes pending the BIO.
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<bio(3)|bio(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>,
|
||||
L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)>
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -31,7 +31,7 @@ not supported.
|
||||
BIO_reset() reinitializes a digest BIO.
|
||||
|
||||
BIO_set_md() sets the message digest of BIO B<b> to B<md>: 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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -25,8 +25,8 @@ BIO_new_bio_pair() does not check whether B<bio1> or B<bio2> do point to
|
||||
some other BIO, the values are overwritten, BIO_free() is not called.
|
||||
|
||||
The two BIOs, even though forming a BIO pair and must be BIO_free()'ed
|
||||
seperately. This can be of importance, as some SSL-functions like SSL_set_bio()
|
||||
or SSL_free() call BIO_free() implicitely, so that the peer-BIO is left
|
||||
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);
|
||||
...
|
||||
|
||||
|
||||
@ -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<not> 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<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to
|
||||
See L<BIO_should_retry(3)|BIO_should_retry(3)> 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<BIO_f_buffer(3)|BIO_f_buffer(3)>
|
||||
to the chain.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<BIO_should_retry(3)|BIO_should_retry(3)>
|
||||
|
||||
TBA
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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<b>. After this call no further
|
||||
writes on BIO B<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<b> to B<size>.
|
||||
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<bio1>, B<bio2>
|
||||
with write buffer sizes B<writebuf1> and B<writebuf2>. 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
|
||||
|
||||
@ -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<ip> 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<port>. B<port> 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.
|
||||
|
||||
@ -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<b> to B<fd> and the close
|
||||
flag to B<c>.
|
||||
|
||||
@ -36,11 +27,20 @@ BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also
|
||||
returns the file descriptor. If B<c> is not NULL it should be of type
|
||||
(int *).
|
||||
|
||||
BIO_new_fd() returns a file desciptor BIO using B<fd> and B<close_flag>.
|
||||
BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
|
||||
|
||||
=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<BIO_read(3)|BIO_read(3)> and L<BIO_should_retry(3)|BIO_should_retry(3)>
|
||||
@ -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<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, TBA
|
||||
L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
|
||||
L<BIO_reset(3)|BIO_reset(3)>, L<BIO_read(3)|BIO_read(3)>,
|
||||
L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
|
||||
L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
|
||||
L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>
|
||||
|
||||
@ -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<mode> the meaning
|
||||
of B<mode> 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<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, TBA
|
||||
L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
|
||||
L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>,
|
||||
L<BIO_read(3)|BIO_read(3)>,
|
||||
L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
|
||||
L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
|
||||
L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -1,30 +0,0 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_seek, BIO_tell - file BIO operations
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
#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<ofs> 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
|
||||
|
||||
@ -39,4 +39,16 @@ BIO).
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
TBA
|
||||
L<BIO_ctrl(3)|BIO_ctrl(3)>,
|
||||
L<BIO_f_base64(3)|BIO_f_base64(3)>,
|
||||
L<BIO_f_cipher(3)|BIO_f_cipher(3)>, L<BIO_f_md(3)|BIO_f_md(3)>,
|
||||
L<BIO_f_null(3)|BIO_f_null(3)>, L<BIO_f_ssl(3)|BIO_f_ssl(3)>,
|
||||
L<BIO_find_type(3)|BIO_find_type(3)>, L<BIO_new(3)|BIO_new(3)>,
|
||||
L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)>,
|
||||
L<BIO_push(3)|BIO_push(3)>, L<BIO_read(3)|BIO_read(3)>,
|
||||
L<BIO_s_accept(3)|BIO_s_accept(3)>, L<BIO_s_bio(3)|BIO_s_bio(3)>,
|
||||
L<BIO_s_connect(3)|BIO_s_connect(3)>, L<BIO_s_fd(3)|BIO_s_fd(3)>,
|
||||
L<BIO_s_file(3)|BIO_s_file(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>,
|
||||
L<BIO_s_null(3)|BIO_s_null(3)>, L<BIO_s_socket(3)|BIO_s_socket(3)>,
|
||||
L<BIO_set_callback(3)|BIO_set_callback(3)>,
|
||||
L<BIO_should_retry(3)|BIO_should_retry(3)>
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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<session> and removes
|
||||
the SSL_SESSION structure pointed to by B<session> and frees up the allocated
|
||||
the B<SSL_SESSION> structure pointed to by B<session> and frees up the allocated
|
||||
memory, if the the reference count has reached 0.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
@ -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<ssl> by setting an underlying B<BIO>. The behaviour of SSL_accept() depends
|
||||
on the underlying BIO.
|
||||
|
||||
If the underlying BIO is B<blocking>, SSL_accept() will only return, once the
|
||||
handshake has been finished or an error occured, except for SGC (Server
|
||||
Gated Cryptography). For SGC SSL_accept() may return with -1 but
|
||||
SSL_get_error() will yield SSL_ERROR_WANT_READ/WRITE and SSL_accept()
|
||||
If the underlying BIO is B<blocking>, 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<SSL_ERROR_WANT_READ/WRITE> and SSL_accept()
|
||||
should be called again.
|
||||
|
||||
If the underlying BIO is B<non-blocking>, SSL_accept() will also return,
|
||||
If the underlying BIO is B<non-blocking>, SSL_accept() will also return
|
||||
when the underlying BIO could not satisfy the needs of SSL_accept()
|
||||
to continue the handshake. In this case a call to SSL_get_error() with the
|
||||
return value of SSL_accept() will yield SSL_ERROR_WANT_READ or
|
||||
SSL_ERROR_WANT_WRITE. The calling process then must repeat the call after
|
||||
return value of SSL_accept() will yield B<SSL_ERROR_WANT_READ> or
|
||||
B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
|
||||
taking appropriate action to satisfy the needs of SSL_accept().
|
||||
The action depends on the underlying BIO. When using a non-blocking socket,
|
||||
nothing is to be done, but select() can be used to check for the required
|
||||
@ -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<ret> to find out the reason.
|
||||
|
||||
=item -1
|
||||
|
||||
The TLS handshake was not successfull, because a fatal error occured either
|
||||
at the protocol level or a connection failure occured. The shutdown was
|
||||
not clean. It can also occure of action is need to continue the operation
|
||||
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<ret>
|
||||
to find out the reason.
|
||||
|
||||
|
||||
@ -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<ssl> to allow another connection. All settings (method, ciphers,
|
||||
BIOs) are kept. A completely negotiated SSL_SESSION is not freed but left
|
||||
untouched for the underlying SSL_CTX.
|
||||
Reset B<ssl> to allow another connection. All settings (method, ciphers,
|
||||
BIOs) are kept. A completely negotiated B<SSL_SESSION> is not freed but left
|
||||
untouched for the underlying B<SSL_CTX>.
|
||||
|
||||
=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
|
||||
|
||||
|
||||
@ -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<ssl> by setting an
|
||||
underlying B<BIO>. The behaviour of SSL_connect() depends on the underlying
|
||||
BIO.
|
||||
|
||||
If the underlying BIO is B<blocking>, SSL_connect() will only return, once the
|
||||
handshake has been finished or an error occured.
|
||||
If the underlying BIO is B<blocking>, SSL_connect() will only return once the
|
||||
handshake has been finished or an error occurred.
|
||||
|
||||
If the underlying BIO is B<non-blocking>, SSL_connect() will also return,
|
||||
If the underlying BIO is B<non-blocking>, SSL_connect() will also return
|
||||
when the underlying BIO could not satisfy the needs of SSL_connect()
|
||||
to continue the handshake. In this case a call to SSL_get_error() with the
|
||||
return value of SSL_connect() will yield SSL_ERROR_WANT_READ or
|
||||
SSL_ERROR_WANT_WRITE. The calling process then must repeat the call after
|
||||
return value of SSL_connect() will yield B<SSL_ERROR_WANT_READ> or
|
||||
B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
|
||||
taking appropriate action to satisfy the needs of SSL_connect().
|
||||
The action depends on the underlying BIO. When using a non-blocking socket,
|
||||
nothing is to be done, but select() can be used to check for the required
|
||||
@ -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<ret> to find out the reason.
|
||||
|
||||
=item -1
|
||||
|
||||
The TLS handshake was not successfull, because a fatal error occured either
|
||||
at the protocol level or a connection failure occured. The shutdown was
|
||||
not clean. It can also occure of action is need to continue the operation
|
||||
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<ret>
|
||||
to find out the reason.
|
||||
|
||||
|
||||
@ -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<ssl> and removes the SSL
|
||||
structure pointed to by B<ssl> and frees up the allocated memory, if the
|
||||
SSL_free() decrements the reference count of B<ssl>, and removes the SSL
|
||||
structure pointed to by B<ssl> and frees up the allocated memory if the
|
||||
the reference count has reached 0.
|
||||
|
||||
It also calls the free()ing procedures for indirectly affected items, if
|
||||
applicable: the buffering BIO, the read and write BIOs,
|
||||
cipher lists especially created for this B<ssl>, the SSL_SESSION.
|
||||
cipher lists specially created for this B<ssl>, the B<SSL_SESSION>.
|
||||
Do not explicitly free these indirectly freed up items before or after
|
||||
calling SSL_free(), as trying to free things twice may lead to program
|
||||
failure.
|
||||
|
||||
@ -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<ssl>. 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<ret>.
|
||||
|
||||
In addition to B<ssl> and B<ret>, 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<ret E<gt> 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<SSL_ERROR_ZERO_RETURN>
|
||||
@ -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<BIO> has data available for reading (if the result code is
|
||||
B<SSL_ERROR_WANT_READ>) or allows writing data (B<SSL_ERROR_WANT_WRITE>).
|
||||
For socket B<BIO>s (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<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>, 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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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<ssl>. The reference count of the SSL session is not incremented, so
|
||||
SSL_get_session() returns a pointer to the B<SSL_SESSION> actually used in
|
||||
B<ssl>. The reference count of the B<SSL_SESSION> is not incremented, so
|
||||
that the pointer can become invalid when the B<ssl> is freed and
|
||||
SSL_SESSION_free() is implicitly called.
|
||||
|
||||
SSL_get0_session() is the same as SSL_get_session().
|
||||
|
||||
SSL_get1_session() is the same as SSL_get_session(), but the reference
|
||||
count of the SSL session is incremented by one.
|
||||
count of the B<SSL_SESSION> is incremented by one.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
|
||||
@ -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<SSL> structure which is needed to hold the data
|
||||
for a SSL connection. The new SSL inherits the settings of the underlying
|
||||
context B<ctx>: connection method (SSLv2/v3/TLSv1), options, verification
|
||||
settings, timeout settings.
|
||||
SSL_new() creates a new B<SSL> structure which is needed to hold the
|
||||
data for a TLS/SSL connection. The new structure inherits the settings
|
||||
of the underlying context B<ctx>: 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.
|
||||
|
||||
|
||||
@ -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<num> bytes from the specified B<ssl> into the
|
||||
buffer B<buf>. If necessary, SSL_read() will negotiate a TLS session, if
|
||||
not already explicitely performed by SSL_connect() or SSL_accept(). If the
|
||||
buffer B<buf>. 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<blocking>, 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<non-blocking>, SSL_read() will also return,
|
||||
If the underlying BIO is B<non-blocking>, SSL_read() will also return
|
||||
when the underlying BIO could not satisfy the needs of SSL_read()
|
||||
to continue the operation. In this case a call to SSL_get_error() with the
|
||||
return value of SSL_read() will yield SSL_ERROR_WANT_READ or
|
||||
SSL_ERROR_WANT_WRITE. As at any time a re-negotiation is possible, a
|
||||
return value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or
|
||||
B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
|
||||
call to SSL_read() can also cause write operations! The calling process
|
||||
then must repeat the call after taking appropriate action to satisfy the
|
||||
needs of SSL_read(). The action depends on the underlying BIO. When using a
|
||||
@ -42,18 +42,18 @@ The following return values can occur:
|
||||
|
||||
=item E<gt>0
|
||||
|
||||
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<ret> 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<ret> to find out the reason.
|
||||
|
||||
|
||||
@ -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<rbio> and B<wbio> for the read and write
|
||||
operations of the TLS (encrypted) side of B<ssl>.
|
||||
operations of the TLS/SSL (encrypted) side of B<ssl>.
|
||||
|
||||
The SSL engine inherits the behaviour of B<rbio> and B<wbio>, respectively.
|
||||
If a BIO is non-blocking, the B<ssl> will also have non-blocking behaviour.
|
||||
@ -29,6 +29,6 @@ SSL_set_bio() cannot fail.
|
||||
|
||||
L<SSL_get_rbio(3)|SSL_get_rbio(3)>,
|
||||
L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>,
|
||||
L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)>
|
||||
L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
|
||||
|
||||
=cut
|
||||
|
||||
@ -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<fd> as the input/output facility
|
||||
for the TLS (encrypted) side of SSL engine. B<fd> will typically be the
|
||||
for the TLS/SSL (encrypted) side of B<ssl>. B<fd> will typically be the
|
||||
socket file descriptor of a network connection.
|
||||
|
||||
When performing the operation, a B<socket BIO> is automatically created to
|
||||
@ -26,8 +26,8 @@ also have non-blocking behaviour.
|
||||
If there was already a BIO connected to B<ssl>, BIO_free() will be called
|
||||
(for both the reading and writing side, if different).
|
||||
|
||||
SSL_set_rfd() and SSL_set_wfd() perform the respective action but only
|
||||
for the read channel or the write channel, which can be set independantly.
|
||||
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
|
||||
|
||||
|
||||
@ -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<session> 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<session> 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<session> is incremented
|
||||
by 1. If the session is not reused, the reference count is decremented
|
||||
again during SSL_connect().
|
||||
|
||||
If there is already a session set inside B<ssl> (because it was set with
|
||||
SSL_set_session() before or because the same B<ssl> was already used for
|
||||
a connection) SSL_SESSION_free() will be called for that session.
|
||||
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
|
||||
|
||||
|
||||
@ -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<blocking>, SSL_shutdown() will only return, once the
|
||||
handshake has been finished or an error occured.
|
||||
If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
|
||||
handshake has been finished or an error occurred.
|
||||
|
||||
If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return,
|
||||
If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return
|
||||
when the underlying BIO could not satisfy the needs of SSL_shutdown()
|
||||
to continue the handshake. In this case a call to SSL_get_error() with the
|
||||
return value of SSL_shutdown() will yield SSL_ERROR_WANT_READ or
|
||||
SSL_ERROR_WANT_WRITE. The calling process then must repeat the call after
|
||||
return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or
|
||||
B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
|
||||
taking appropriate action to satisfy the needs of SSL_shutdown().
|
||||
The action depends on the underlying BIO. When using a non-blocking socket,
|
||||
nothing is to be done, but select() can be used to check for the required
|
||||
@ -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<ret> to find out the reason.
|
||||
|
||||
=item -1
|
||||
|
||||
The shutdown was not successfull, because a fatal error occured either
|
||||
at the protocol level or a connection failure occured. It can also occure of
|
||||
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<ret> to find out the reason.
|
||||
|
||||
|
||||
@ -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<num> bytes from the buffer B<buf> into the specified
|
||||
B<ssl>. If necessary, SSL_write() will negotiate a TLS session, if
|
||||
not already explicitely performed by SSL_connect() or SSL_accept(). If the
|
||||
B<ssl>. 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<blocking>, 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<non-blocking>, SSL_write() will also return,
|
||||
when the underlying BIO could not satisfy the needs of SSL_write()
|
||||
to continue the operation. In this case a call to SSL_get_error() with the
|
||||
return value of SSL_write() will yield SSL_ERROR_WANT_READ or
|
||||
SSL_ERROR_WANT_WRITE. As at any time a re-negotiation is possible, a
|
||||
return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or
|
||||
B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
|
||||
call to SSL_write() can also cause write operations! The calling process
|
||||
then must repeat the call after taking appropriate action to satisfy the
|
||||
needs of SSL_write(). The action depends on the underlying BIO. When using a
|
||||
@ -42,17 +42,17 @@ The following return values can occur:
|
||||
|
||||
=item E<gt>0
|
||||
|
||||
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<ret> to find out, whether an error occured.
|
||||
The write operation was not successful. Call SSL_get_error() with the return
|
||||
value B<ret> 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<ret> to find out the reason.
|
||||
|
||||
|
||||
@ -83,7 +83,7 @@ B<SSL> structures which are later created for the connections.
|
||||
|
||||
=item B<SSL_SESSION> (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: B<SSL_CIPHER>s, client and server certificates, keys, etc.
|
||||
|
||||
=item B<SSL> (SSL Connection)
|
||||
@ -624,7 +624,16 @@ connection defined in the B<SSL> structure.
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<openssl(1)|openssl(1)>, L<crypto(3)|crypto(3)>,
|
||||
L<SSL_get_error(3)|SSL_get_error(3)>
|
||||
L<SSL_accept(3)|SSL_accept(3)>, L<SSL_clear(3)|SSL_clear(3)>,
|
||||
L<SSL_connect(3)|SSL_connect(3)>, L<SSL_free(3)|SSL_free(3)>,
|
||||
L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_get_fd(3)|SSL_get_fd(3)>,
|
||||
L<SSL_get_rbio(3)|SSL_get_rbio(3)>,
|
||||
L<SSL_get_session(3)|SSL_get_session(3)>, L<SSL_new(3)|SSL_new(3)>,
|
||||
L<SSL_read(3)|SSL_read(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>,
|
||||
L<SSL_set_fd(3)|SSL_set_fd(3)>,
|
||||
L<SSL_set_session(3)|SSL_set_session(3)>,
|
||||
L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_write(3)|SSL_write(3)>,
|
||||
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user