summaryrefslogtreecommitdiff
path: root/src/lib/libssl
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libssl')
-rw-r--r--src/lib/libssl/src/doc/crypto/BIO_push.pod67
-rw-r--r--src/lib/libssl/src/doc/crypto/BIO_read.pod66
-rw-r--r--src/lib/libssl/src/doc/crypto/BIO_s_accept.pod189
-rw-r--r--src/lib/libssl/src/doc/crypto/BIO_s_bio.pod185
-rw-r--r--src/lib/libssl/src/doc/crypto/BIO_s_connect.pod191
-rw-r--r--src/lib/libssl/src/doc/crypto/BIO_s_fd.pod91
-rw-r--r--src/lib/libssl/src/doc/crypto/BIO_s_file.pod150
-rw-r--r--src/lib/libssl/src/doc/crypto/BIO_s_mem.pod112
-rw-r--r--src/lib/libssl/src/doc/crypto/BIO_s_null.pod35
-rw-r--r--src/lib/libssl/src/doc/crypto/BIO_s_socket.pod61
-rw-r--r--src/lib/libssl/src/doc/crypto/BIO_set_callback.pod105
-rw-r--r--src/lib/libssl/src/doc/crypto/BIO_should_retry.pod112
12 files changed, 0 insertions, 1364 deletions
diff --git a/src/lib/libssl/src/doc/crypto/BIO_push.pod b/src/lib/libssl/src/doc/crypto/BIO_push.pod
deleted file mode 100644
index 39c964b272..0000000000
--- a/src/lib/libssl/src/doc/crypto/BIO_push.pod
+++ /dev/null
@@ -1,67 +0,0 @@
1=pod
2
3=head1 NAME
4
5BIO_push, BIO_pop - add and remove BIOs from a chain.
6
7=head1 SYNOPSIS
8
9 #include <openssl/bio.h>
10
11 BIO * BIO_push(BIO *b,BIO *append);
12 BIO * BIO_pop(BIO *b);
13
14=head1 DESCRIPTION
15
16The BIO_push() function appends the BIO B<append> to B<b>, and returns
17B<b>.
18
19BIO_pop() removes the BIO B<b> from a chain and returns the next BIO
20in the chain, or NULL if there is no next BIO. The removed BIO then
21becomes a single BIO with no association with the original chain,
22it can thus be freed or attached to a different chain.
23
24=head1 NOTES
25
26The names of these functions are perhaps a little misleading. BIO_push()
27joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain,
28the deleted BIO does not need to be at the end of a chain.
29
30The process of calling BIO_push() and BIO_pop() on a BIO may have additional
31consequences (a control call is made to the affected BIOs) any effects will
32be noted in the descriptions of individual BIOs.
33
34=head1 EXAMPLES
35
36For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
37a base64 BIO and B<f> is a file BIO.
38
39If the call:
40
41 BIO_push(b64, f);
42
43is made then the new chain will be B<b64-f>. After making the calls
44
45 BIO_push(md2, b64);
46 BIO_push(md1, md2);
47
48the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested
49by B<md1> and B<md2>, B<base64> encoded and written to B<f>.
50
51It should be noted that reading causes data to pass in the reverse
52direction, that is data is read from B<f>, base64 B<decoded> and digested
53by B<md1> and B<md2>. If the call:
54
55 BIO_pop(md2);
56
57The call will return B<b64> and the new chain will be B<md1-b64-f>; data can
58be written to B<md1> as before.
59
60=head1 RETURN VALUES
61
62BIO_push() returns the beginning of the chain, B<b>.
63
64BIO_pop() returns the next BIO in the chain, or NULL if there is no next
65BIO.
66
67=cut
diff --git a/src/lib/libssl/src/doc/crypto/BIO_read.pod b/src/lib/libssl/src/doc/crypto/BIO_read.pod
deleted file mode 100644
index e527bff8d0..0000000000
--- a/src/lib/libssl/src/doc/crypto/BIO_read.pod
+++ /dev/null
@@ -1,66 +0,0 @@
1=pod
2
3=head1 NAME
4
5BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
6
7=head1 SYNOPSIS
8
9 #include <openssl/bio.h>
10
11 int BIO_read(BIO *b, void *buf, int len);
12 int BIO_gets(BIO *b, char *buf, int size);
13 int BIO_write(BIO *b, const void *buf, int len);
14 int BIO_puts(BIO *b, const char *buf);
15
16=head1 DESCRIPTION
17
18BIO_read() attempts to read B<len> bytes from BIO B<b> and places
19the data in B<buf>.
20
21BIO_gets() performs the BIOs "gets" operation and places the data
22in B<buf>. Usually this operation will attempt to read a line of data
23from the BIO of maximum length B<len>. There are exceptions to this
24however, for example BIO_gets() on a digest BIO will calculate and
25return the digest and other BIOs may not support BIO_gets() at all.
26
27BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>.
28
29BIO_puts() attempts to write a null terminated string B<buf> to BIO B<b>.
30
31=head1 RETURN VALUES
32
33All these functions return either the amount of data successfully read or
34written (if the return value is positive) or that no data was successfully
35read or written if the result is 0 or -1. If the return value is -2 then
36the operation is not implemented in the specific BIO type.
37
38=head1 NOTES
39
40A 0 or -1 return is not necessarily an indication of an error. In
41particular when the source/sink is non-blocking or of a certain type
42it may merely be an indication that no data is currently available and that
43the application should retry the operation later.
44
45One technique sometimes used with blocking sockets is to use a system call
46(such as select(), poll() or equivalent) to determine when data is available
47and then call read() to read the data. The equivalent with BIOs (that is call
48select() on the underlying I/O structure and then call BIO_read() to
49read the data) should B<not> be used because a single call to BIO_read()
50can cause several reads (and writes in the case of SSL BIOs) on the underlying
51I/O structure and may block as a result. Instead select() (or equivalent)
52should be combined with non blocking I/O so successive reads will request
53a retry instead of blocking.
54
55See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to
56determine the cause of a retry and other I/O issues.
57
58If the BIO_gets() function is not supported by a BIO then it possible to
59work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)>
60to the chain.
61
62=head1 SEE ALSO
63
64L<BIO_should_retry(3)|BIO_should_retry(3)>
65
66=cut
diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_accept.pod b/src/lib/libssl/src/doc/crypto/BIO_s_accept.pod
deleted file mode 100644
index 5729d38193..0000000000
--- a/src/lib/libssl/src/doc/crypto/BIO_s_accept.pod
+++ /dev/null
@@ -1,189 +0,0 @@
1=pod
2
3=head1 NAME
4
5BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, BIO_new_accept,
6BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode,
7BIO_get_bind_mode, BIO_do_accept - accept BIO
8
9=head1 SYNOPSIS
10
11 #include <openssl/bio.h>
12
13 BIO_METHOD *BIO_s_accept(void);
14
15 long BIO_set_accept_port(BIO *b, char *name);
16 char *BIO_get_accept_port(BIO *b);
17
18 BIO *BIO_new_accept(char *host_port);
19
20 long BIO_set_nbio_accept(BIO *b, int n);
21 long BIO_set_accept_bios(BIO *b, char *bio);
22
23 long BIO_set_bind_mode(BIO *b, long mode);
24 long BIO_get_bind_mode(BIO *b, long dummy);
25
26 #define BIO_BIND_NORMAL 0
27 #define BIO_BIND_REUSEADDR_IF_UNUSED 1
28 #define BIO_BIND_REUSEADDR 2
29
30 int BIO_do_accept(BIO *b);
31
32=head1 DESCRIPTION
33
34BIO_s_accept() returns the accept BIO method. This is a wrapper
35round the platform's TCP/IP socket accept routines.
36
37Using accept BIOs, TCP/IP connections can be accepted and data
38transferred using only BIO routines. In this way any platform
39specific operations are hidden by the BIO abstraction.
40
41Read and write operations on an accept BIO will perform I/O
42on the underlying connection. If no connection is established
43and the port (see below) is set up properly then the BIO
44waits for an incoming connection.
45
46Accept BIOs support BIO_puts() but not BIO_gets().
47
48If the close flag is set on an accept BIO then any active
49connection on that chain is shutdown and the socket closed when
50the BIO is freed.
51
52Calling BIO_reset() on a accept BIO will close any active
53connection and reset the BIO into a state where it awaits another
54incoming connection.
55
56BIO_get_fd() and BIO_set_fd() can be called to retrieve or set
57the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)>
58
59BIO_set_accept_port() uses the string B<name> to set the accept
60port. The port is represented as a string of the form "host:port",
61where "host" is the interface to use and "port" is the port.
62Either or both values can be "*" which is interpreted as meaning
63any interface or port respectively. "port" has the same syntax
64as the port specified in BIO_set_conn_port() for connect BIOs,
65that is it can be a numerical port string or a string to lookup
66using getservbyname() and a string table.
67
68BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into
69a single call: that is it creates a new accept BIO with port
70B<host_port>.
71
72BIO_set_nbio_accept() sets the accept socket to blocking mode
73(the default) if B<n> is 0 or non blocking mode if B<n> is 1.
74
75BIO_set_accept_bios() can be used to set a chain of BIOs which
76will be duplicated and prepended to the chain when an incoming
77connection is received. This is useful if, for example, a
78buffering or SSL BIO is required for each connection. The
79chain of BIOs must not be freed after this call, they will
80be automatically freed when the accept BIO is freed.
81
82BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve
83the current bind mode. If BIO_BIND_NORMAL (the default) is set
84then another socket cannot be bound to the same port. If
85BIO_BIND_REUSEADDR is set then other sockets can bind to the
86same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and
87attempt is first made to use BIO_BIN_NORMAL, if this fails
88and the port is not in use then a second attempt is made
89using BIO_BIND_REUSEADDR.
90
91BIO_do_accept() serves two functions. When it is first
92called, after the accept BIO has been setup, it will attempt
93to create the accept socket and bind an address to it. Second
94and subsequent calls to BIO_do_accept() will await an incoming
95connection, or request a retry in non blocking mode.
96
97=head1 NOTES
98
99When an accept BIO is at the end of a chain it will await an
100incoming connection before processing I/O calls. When an accept
101BIO is not at then end of a chain it passes I/O calls to the next
102BIO in the chain.
103
104When a connection is established a new socket BIO is created for
105the connection and appended to the chain. That is the chain is now
106accept->socket. This effectively means that attempting I/O on
107an initial accept socket will await an incoming connection then
108perform I/O on it.
109
110If any additional BIOs have been set using BIO_set_accept_bios()
111then they are placed between the socket and the accept BIO,
112that is the chain will be accept->otherbios->socket.
113
114If a server wishes to process multiple connections (as is normally
115the case) then the accept BIO must be made available for further
116incoming connections. This can be done by waiting for a connection and
117then calling:
118
119 connection = BIO_pop(accept);
120
121After this call B<connection> will contain a BIO for the recently
122established connection and B<accept> will now be a single BIO
123again which can be used to await further incoming connections.
124If no further connections will be accepted the B<accept> can
125be freed using BIO_free().
126
127If only a single connection will be processed it is possible to
128perform I/O using the accept BIO itself. This is often undesirable
129however because the accept BIO will still accept additional incoming
130connections. This can be resolved by using BIO_pop() (see above)
131and freeing up the accept BIO after the initial connection.
132
133If the underlying accept socket is non-blocking and BIO_do_accept() is
134called to await an incoming connection it is possible for
135BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens
136then it is an indication that an accept attempt would block: the application
137should take appropriate action to wait until the underlying socket has
138accepted a connection and retry the call.
139
140BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(),
141BIO_set_accept_bios(), BIO_set_bind_mode(), BIO_get_bind_mode() and
142BIO_do_accept() are macros.
143
144=head1 EXAMPLE
145
146This example accepts two connections on port 4444, sends messages
147down each and finally closes both down.
148
149 BIO *abio, *cbio, *cbio2;
150 ERR_load_crypto_strings();
151 abio = BIO_new_accept("4444");
152
153 /* First call to BIO_accept() sets up accept BIO */
154 if (BIO_do_accept(abio) <= 0) {
155 fprintf(stderr, "Error setting up accept\n");
156 ERR_print_errors_fp(stderr);
157 exit(0);
158 }
159
160 /* Wait for incoming connection */
161 if (BIO_do_accept(abio) <= 0) {
162 fprintf(stderr, "Error accepting connection\n");
163 ERR_print_errors_fp(stderr);
164 exit(0);
165 }
166 fprintf(stderr, "Connection 1 established\n");
167 /* Retrieve BIO for connection */
168 cbio = BIO_pop(abio);
169 BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n");
170 fprintf(stderr, "Sent out data on connection 1\n");
171 /* Wait for another connection */
172 if (BIO_do_accept(abio) <= 0) {
173 fprintf(stderr, "Error accepting connection\n");
174 ERR_print_errors_fp(stderr);
175 exit(0);
176 }
177 fprintf(stderr, "Connection 2 established\n");
178 /* Close accept BIO to refuse further connections */
179 cbio2 = BIO_pop(abio);
180 BIO_free(abio);
181 BIO_puts(cbio2, "Connection 2: Sending out Data on second\n");
182 fprintf(stderr, "Sent out data on connection 2\n");
183
184 BIO_puts(cbio, "Connection 1: Second connection established\n");
185 /* Close the two established connections */
186 BIO_free(cbio);
187 BIO_free(cbio2);
188
189=cut
diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_bio.pod b/src/lib/libssl/src/doc/crypto/BIO_s_bio.pod
deleted file mode 100644
index 61ded32a02..0000000000
--- a/src/lib/libssl/src/doc/crypto/BIO_s_bio.pod
+++ /dev/null
@@ -1,185 +0,0 @@
1=pod
2
3=head1 NAME
4
5BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
6BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair,
7BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request,
8BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
9
10=head1 SYNOPSIS
11
12 #include <openssl/bio.h>
13
14 BIO_METHOD *BIO_s_bio(void);
15
16 #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2)
17 #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL)
18
19 #define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL)
20
21 #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL)
22 #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL)
23
24 int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
25
26 #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL)
27 size_t BIO_ctrl_get_write_guarantee(BIO *b);
28
29 #define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL)
30 size_t BIO_ctrl_get_read_request(BIO *b);
31
32 int BIO_ctrl_reset_read_request(BIO *b);
33
34=head1 DESCRIPTION
35
36BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of
37source/sink BIOs where data written to either half of the pair is buffered and
38can be read from the other half. Both halves must usually by handled by the
39same application thread since no locking is done on the internal data
40structures.
41
42Since BIO chains typically end in a source/sink BIO it is possible to make this
43one half of a BIO pair and have all the data processed by the chain under
44application control.
45
46One typical use of BIO pairs is to place TLS/SSL I/O under application control,
47this can be used when the application wishes to use a non standard transport
48for TLS/SSL or the normal socket routines are inappropriate.
49
50Calls to BIO_read() will read data from the buffer or request a retry if no
51data is available.
52
53Calls to BIO_write() will place data in the buffer or request a retry if the
54buffer is full.
55
56The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to
57determine the amount of pending data in the read or write buffer.
58
59BIO_reset() clears any data in the write buffer.
60
61BIO_make_bio_pair() joins two separate BIOs into a connected pair.
62
63BIO_destroy_pair() destroys the association between two connected BIOs. Freeing
64up any half of the pair will automatically destroy the association.
65
66BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further
67writes on BIO B<b> are allowed (they will return an error). Reads on the other
68half of the pair will return any pending data or EOF when all pending data has
69been read.
70
71BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>.
72If the size is not initialized a default value is used. This is currently
7317K, sufficient for a maximum size TLS record.
74
75BIO_get_write_buf_size() returns the size of the write buffer.
76
77BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and
78BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2>
79with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is
80zero then the default size is used. BIO_new_bio_pair() does not check whether
81B<bio1> or B<bio2> do point to some other BIO, the values are overwritten,
82BIO_free() is not called.
83
84BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum
85length of data that can be currently written to the BIO. Writes larger than
86this value will return a value from BIO_write() less than the amount requested
87or if the buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a
88function whereas BIO_get_write_guarantee() is a macro.
89
90BIO_get_read_request() and BIO_ctrl_get_read_request() return the
91amount of data requested, or the buffer size if it is less, if the
92last read attempt at the other half of the BIO pair failed due to an
93empty buffer. This can be used to determine how much data should be
94written to the BIO so the next read will succeed: this is most useful
95in TLS/SSL applications where the amount of data read is usually
96meaningful rather than just a buffer size. After a successful read
97this call will return zero. It also will return zero once new data
98has been written satisfying the read request or part of it.
99Note that BIO_get_read_request() never returns an amount larger
100than that returned by BIO_get_write_guarantee().
101
102BIO_ctrl_reset_read_request() can also be used to reset the value returned by
103BIO_get_read_request() to zero.
104
105=head1 NOTES
106
107Both halves of a BIO pair should be freed. That is even if one half is implicit
108freed due to a BIO_free_all() or SSL_free() call the other half needs to be
109freed.
110
111When used in bidirectional applications (such as TLS/SSL) care should be taken
112to flush any data in the write buffer. This can be done by calling
113BIO_pending() on the other half of the pair and, if any data is pending,
114reading it and sending it to the underlying transport. This must be done before
115any normal processing (such as calling select() ) due to a request and
116BIO_should_read() being true.
117
118To see why this is important consider a case where a request is sent using
119BIO_write() and a response read with BIO_read(), this can occur during an
120TLS/SSL handshake for example. BIO_write() will succeed and place data in the
121write buffer. BIO_read() will initially fail and BIO_should_read() will be
122true. If the application then waits for data to be available on the underlying
123transport before flushing the write buffer it will never succeed because the
124request was never sent!
125
126=head1 RETURN VALUES
127
128BIO_new_bio_pair() returns 1 on success, with the new BIOs available in
129B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the
130locations for B<bio1> and B<bio2>. Check the error stack for more information.
131
132[TODO: More return values need to be added here]
133
134=head1 EXAMPLE
135
136The BIO pair can be used to have full control over the network access of an
137application. The application can call select() on the socket as required
138without having to go through the SSL-interface.
139
140 BIO *internal_bio, *network_bio;
141 ...
142 BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
143 SSL_set_bio(ssl, internal_bio, internal_bio);
144 SSL_operations();
145 ...
146
147 application | TLS-engine
148 | |
149 +----------> SSL_operations()
150 | /\ ||
151 | || \/
152 | BIO-pair (internal_bio)
153 +----------< BIO-pair (network_bio)
154 | |
155 socket |
156
157 ...
158 SSL_free(ssl); /* implicitly frees internal_bio */
159 BIO_free(network_bio);
160 ...
161
162As the BIO pair will only buffer the data and never directly access the
163connection, it behaves non-blocking and will return as soon as the write
164buffer is full or the read buffer is drained. Then the application has to
165flush the write buffer and/or fill the read buffer.
166
167Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO
168and must be transfered to the network. Use BIO_ctrl_get_read_request() to
169find out, how many bytes must be written into the buffer before the
170SSL_operation() can successfully be continued.
171
172=head1 WARNING
173
174As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ
175condition, but there is still data in the write buffer. An application must
176not rely on the error value of SSL_operation() but must assure that the
177write buffer is always flushed first. Otherwise a deadlock may occur as
178the peer might be waiting for the data before being able to continue.
179
180=head1 SEE ALSO
181
182L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
183L<BIO_should_retry(3)|BIO_should_retry(3)>, L<BIO_read(3)|BIO_read(3)>
184
185=cut
diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_connect.pod b/src/lib/libssl/src/doc/crypto/BIO_s_connect.pod
deleted file mode 100644
index 45832e52f3..0000000000
--- a/src/lib/libssl/src/doc/crypto/BIO_s_connect.pod
+++ /dev/null
@@ -1,191 +0,0 @@
1=pod
2
3=head1 NAME
4
5BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port,
6BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
7BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
8BIO_set_nbio, BIO_do_connect - connect BIO
9
10=head1 SYNOPSIS
11
12 #include <openssl/bio.h>
13
14 BIO_METHOD * BIO_s_connect(void);
15
16 BIO *BIO_new_connect(char *name);
17
18 long BIO_set_conn_hostname(BIO *b, char *name);
19 long BIO_set_conn_port(BIO *b, char *port);
20 long BIO_set_conn_ip(BIO *b, char *ip);
21 long BIO_set_conn_int_port(BIO *b, char *port);
22 char *BIO_get_conn_hostname(BIO *b);
23 char *BIO_get_conn_port(BIO *b);
24 char *BIO_get_conn_ip(BIO *b, dummy);
25 long BIO_get_conn_int_port(BIO *b, int port);
26
27 long BIO_set_nbio(BIO *b, long n);
28
29 int BIO_do_connect(BIO *b);
30
31=head1 DESCRIPTION
32
33BIO_s_connect() returns the connect BIO method. This is a wrapper
34round the platform's TCP/IP socket connection routines.
35
36Using connect BIOs, TCP/IP connections can be made and data
37transferred using only BIO routines. In this way any platform
38specific operations are hidden by the BIO abstraction.
39
40Read and write operations on a connect BIO will perform I/O
41on the underlying connection. If no connection is established
42and the port and hostname (see below) is set up properly then
43a connection is established first.
44
45Connect BIOs support BIO_puts() but not BIO_gets().
46
47If the close flag is set on a connect BIO then any active
48connection is shutdown and the socket closed when the BIO
49is freed.
50
51Calling BIO_reset() on a connect BIO will close any active
52connection and reset the BIO into a state where it can connect
53to the same host again.
54
55BIO_get_fd() places the underlying socket in B<c> if it is not NULL,
56it also returns the socket . If B<c> is not NULL it should be of
57type (int *).
58
59BIO_set_conn_hostname() uses the string B<name> to set the hostname.
60The hostname can be an IP address. The hostname can also include the
61port in the form hostname:port . It is also acceptable to use the
62form "hostname/any/other/path" or "hostname:port/any/other/path".
63
64BIO_set_conn_port() sets the port to B<port>. B<port> can be the
65numerical form or a string such as "http". A string will be looked
66up first using getservbyname() on the host platform but if that
67fails a standard table of port names will be used. Currently the
68list is http, telnet, socks, https, ssl, ftp, gopher and wais.
69
70BIO_set_conn_ip() sets the IP address to B<ip> using binary form,
71that is four bytes specifying the IP address in big-endian form.
72
73BIO_set_conn_int_port() sets the port using B<port>. B<port> should
74be of type (int *).
75
76BIO_get_conn_hostname() returns the hostname of the connect BIO or
77NULL if the BIO is initialized but no hostname is set.
78This return value is an internal pointer which should not be modified.
79
80BIO_get_conn_port() returns the port as a string.
81
82BIO_get_conn_ip() returns the IP address in binary form.
83
84BIO_get_conn_int_port() returns the port as an int.
85
86BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is
87zero then blocking I/O is set. If B<n> is 1 then non blocking I/O
88is set. Blocking I/O is the default. The call to BIO_set_nbio()
89should be made before the connection is established because
90non blocking I/O is set during the connect process.
91
92BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
93a single call: that is it creates a new connect BIO with B<name>.
94
95BIO_do_connect() attempts to connect the supplied BIO. It returns 1
96if the connection was established successfully. A zero or negative
97value is returned if the connection could not be established, the
98call BIO_should_retry() should be used for non blocking connect BIOs
99to determine if the call should be retried.
100
101=head1 NOTES
102
103If blocking I/O is set then a non positive return value from any
104I/O call is caused by an error condition, although a zero return
105will normally mean that the connection was closed.
106
107If the port name is supplied as part of the host name then this will
108override any value set with BIO_set_conn_port(). This may be undesirable
109if the application does not wish to allow connection to arbitrary
110ports. This can be avoided by checking for the presence of the ':'
111character in the passed hostname and either indicating an error or
112truncating the string at that point.
113
114The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(),
115BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a
116connection attempt is made. Before any connection attempt the values
117returned are those set by the application itself.
118
119Applications do not have to call BIO_do_connect() but may wish to do
120so to separate the connection process from other I/O processing.
121
122If non blocking I/O is set then retries will be requested as appropriate.
123
124It addition to BIO_should_read() and BIO_should_write() it is also
125possible for BIO_should_io_special() to be true during the initial
126connection process with the reason BIO_RR_CONNECT. If this is returned
127then this is an indication that a connection attempt would block,
128the application should then take appropriate action to wait until
129the underlying socket has connected and retry the call.
130
131BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(),
132BIO_set_conn_int_port(), BIO_get_conn_hostname(), BIO_get_conn_port(),
133BIO_get_conn_ip(), BIO_get_conn_int_port(), BIO_set_nbio() and
134BIO_do_connect() are macros.
135
136=head1 RETURN VALUES
137
138BIO_s_connect() returns the connect BIO method.
139
140BIO_get_fd() returns the socket or -1 if the BIO has not
141been initialized.
142
143BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and
144BIO_set_conn_int_port() always return 1.
145
146BIO_get_conn_hostname() returns the connected hostname or NULL is
147none was set.
148
149BIO_get_conn_port() returns a string representing the connected
150port or NULL if not set.
151
152BIO_get_conn_ip() returns a pointer to the connected IP address in
153binary form or all zeros if not set.
154
155BIO_get_conn_int_port() returns the connected port or 0 if none was
156set.
157
158BIO_set_nbio() always returns 1.
159
160BIO_do_connect() returns 1 if the connection was successfully
161established and 0 or -1 if the connection failed.
162
163=head1 EXAMPLE
164
165This is example connects to a webserver on the local host and attempts
166to retrieve a page and copy the result to standard output.
167
168
169 BIO *cbio, *out;
170 int len;
171 char tmpbuf[1024];
172
173 ERR_load_crypto_strings();
174 cbio = BIO_new_connect("localhost:http");
175 out = BIO_new_fp(stdout, BIO_NOCLOSE);
176 if (BIO_do_connect(cbio) <= 0) {
177 fprintf(stderr, "Error connecting to server\n");
178 ERR_print_errors_fp(stderr);
179 /* whatever ... */
180 }
181 BIO_puts(cbio, "GET / HTTP/1.0\n\n");
182 for(;;) {
183 len = BIO_read(cbio, tmpbuf, 1024);
184 if (len <= 0)
185 break;
186 BIO_write(out, tmpbuf, len);
187 }
188 BIO_free(cbio);
189 BIO_free(out);
190
191=cut
diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_fd.pod b/src/lib/libssl/src/doc/crypto/BIO_s_fd.pod
deleted file mode 100644
index 22b7575ba0..0000000000
--- a/src/lib/libssl/src/doc/crypto/BIO_s_fd.pod
+++ /dev/null
@@ -1,91 +0,0 @@
1=pod
2
3=head1 NAME
4
5BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
6
7=head1 SYNOPSIS
8
9 #include <openssl/bio.h>
10
11 BIO_METHOD * BIO_s_fd(void);
12
13 #define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd)
14 #define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c)
15
16 BIO *BIO_new_fd(int fd, int close_flag);
17
18=head1 DESCRIPTION
19
20BIO_s_fd() returns the file descriptor BIO method. This is a wrapper
21round the platforms file descriptor routines such as read() and write().
22
23BIO_read() and BIO_write() read or write the underlying descriptor.
24BIO_puts() is supported but BIO_gets() is not.
25
26If the close flag is set then then close() is called on the underlying
27file descriptor when the BIO is freed.
28
29BIO_reset() attempts to change the file pointer to the start of file
30using lseek(fd, 0, 0).
31
32BIO_seek() sets the file pointer to position B<ofs> from start of file
33using lseek(fd, ofs, 0).
34
35BIO_tell() returns the current file position by calling lseek(fd, 0, 1).
36
37BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close
38flag to B<c>.
39
40BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also
41returns the file descriptor. If B<c> is not NULL it should be of type
42(int *).
43
44BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
45
46=head1 NOTES
47
48The behaviour of BIO_read() and BIO_write() depends on the behavior of the
49platforms read() and write() calls on the descriptor. If the underlying file
50descriptor is in a non blocking mode then the BIO will behave in the manner
51described in the L<BIO_read(3)|BIO_read(3)> and
52L<BIO_should_retry(3)|BIO_should_retry(3)> manual pages.
53
54File descriptor BIOs should not be used for socket I/O. Use socket BIOs
55instead.
56
57=head1 RETURN VALUES
58
59BIO_s_fd() returns the file descriptor BIO method.
60
61BIO_reset() returns zero for success and -1 if an error occurred.
62BIO_seek() and BIO_tell() return the current file position or -1
63is an error occurred. These values reflect the underlying lseek()
64behaviour.
65
66BIO_set_fd() always returns 1.
67
68BIO_get_fd() returns the file descriptor or -1 if the BIO has not
69been initialized.
70
71BIO_new_fd() returns the newly allocated BIO or NULL is an error
72occurred.
73
74=head1 EXAMPLE
75
76This is a file descriptor BIO version of "Hello World":
77
78 BIO *out;
79 out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
80 BIO_printf(out, "Hello World\n");
81 BIO_free(out);
82
83=head1 SEE ALSO
84
85L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
86L<BIO_reset(3)|BIO_reset(3)>, L<BIO_read(3)|BIO_read(3)>,
87L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
88L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
89L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>
90
91=cut
diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_file.pod b/src/lib/libssl/src/doc/crypto/BIO_s_file.pod
deleted file mode 100644
index 0c9cb824da..0000000000
--- a/src/lib/libssl/src/doc/crypto/BIO_s_file.pod
+++ /dev/null
@@ -1,150 +0,0 @@
1=pod
2
3=head1 NAME
4
5BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp,
6BIO_read_filename, BIO_write_filename, BIO_append_filename,
7BIO_rw_filename - FILE bio
8
9=head1 SYNOPSIS
10
11 #include <openssl/bio.h>
12
13 BIO_METHOD * BIO_s_file(void);
14 BIO *BIO_new_file(const char *filename, const char *mode);
15 BIO *BIO_new_fp(FILE *stream, int flags);
16
17 BIO_set_fp(BIO *b,FILE *fp, int flags);
18 BIO_get_fp(BIO *b,FILE **fpp);
19
20 int BIO_read_filename(BIO *b, char *name)
21 int BIO_write_filename(BIO *b, char *name)
22 int BIO_append_filename(BIO *b, char *name)
23 int BIO_rw_filename(BIO *b, char *name)
24
25=head1 DESCRIPTION
26
27BIO_s_file() returns the BIO file method. As its name implies it
28is a wrapper round the stdio FILE structure and it is a
29source/sink BIO.
30
31Calls to BIO_read() and BIO_write() read and write data to the
32underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs.
33
34BIO_flush() on a file BIO calls the fflush() function on the wrapped
35stream.
36
37BIO_reset() attempts to change the file pointer to the start of file
38using fseek(stream, 0, 0).
39
40BIO_seek() sets the file pointer to position B<ofs> from start of file
41using fseek(stream, ofs, 0).
42
43BIO_eof() calls feof().
44
45Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO
46is freed.
47
48BIO_new_file() creates a new file BIO with mode B<mode> the meaning
49of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE
50flag is set on the returned BIO.
51
52BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be:
53BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying
54stream to text mode, default is binary: this only has any effect under
55Win32).
56
57BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same
58meaning as in BIO_new_fp(), it is a macro.
59
60BIO_get_fp() retrieves the fp of a file BIO, it is a macro.
61
62BIO_seek() is a macro that sets the position pointer to B<offset> bytes
63from the start of file.
64
65BIO_tell() returns the value of the position pointer.
66
67BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
68BIO_rw_filename() set the file BIO B<b> to use file B<name> for
69reading, writing, append or read write respectively.
70
71=head1 NOTES
72
73When wrapping stdout, stdin or stderr the underlying stream should not
74normally be closed so the BIO_NOCLOSE flag should be set.
75
76Because the file BIO calls the underlying stdio functions any quirks
77in stdio behaviour will be mirrored by the corresponding BIO.
78
79On Windows BIO_new_files reserves for the filename argument to be
80UTF-8 encoded. In other words if you have to make it work in multi-
81lingual environment, encode file names in UTF-8.
82
83=head1 EXAMPLES
84
85File BIO "hello world":
86
87 BIO *bio_out;
88 bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
89 BIO_printf(bio_out, "Hello World\n");
90
91Alternative technique:
92
93 BIO *bio_out;
94 bio_out = BIO_new(BIO_s_file());
95 if(bio_out == NULL) /* Error ... */
96 if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
97 BIO_printf(bio_out, "Hello World\n");
98
99Write to a file:
100
101 BIO *out;
102 out = BIO_new_file("filename.txt", "w");
103 if(!out) /* Error occurred */
104 BIO_printf(out, "Hello World\n");
105 BIO_free(out);
106
107Alternative technique:
108
109 BIO *out;
110 out = BIO_new(BIO_s_file());
111 if(out == NULL) /* Error ... */
112 if(!BIO_write_filename(out, "filename.txt")) /* Error ... */
113 BIO_printf(out, "Hello World\n");
114 BIO_free(out);
115
116=head1 RETURN VALUES
117
118BIO_s_file() returns the file BIO method.
119
120BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
121occurred.
122
123BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure
124(although the current implementation never return 0).
125
126BIO_seek() returns the same value as the underlying fseek() function:
1270 for success or -1 for failure.
128
129BIO_tell() returns the current file position.
130
131BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
132BIO_rw_filename() return 1 for success or 0 for failure.
133
134=head1 BUGS
135
136BIO_reset() and BIO_seek() are implemented using fseek() on the underlying
137stream. The return value for fseek() is 0 for success or -1 if an error
138occurred this differs from other types of BIO which will typically return
1391 for success and a non positive value if an error occurred.
140
141=head1 SEE ALSO
142
143L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
144L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>,
145L<BIO_read(3)|BIO_read(3)>,
146L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
147L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
148L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>
149
150=cut
diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_mem.pod b/src/lib/libssl/src/doc/crypto/BIO_s_mem.pod
deleted file mode 100644
index 4541b3fc55..0000000000
--- a/src/lib/libssl/src/doc/crypto/BIO_s_mem.pod
+++ /dev/null
@@ -1,112 +0,0 @@
1=pod
2
3=head1 NAME
4
5BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
6BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
7
8=head1 SYNOPSIS
9
10 #include <openssl/bio.h>
11
12 BIO_METHOD * BIO_s_mem(void);
13
14 BIO_set_mem_eof_return(BIO *b,int v)
15 long BIO_get_mem_data(BIO *b, char **pp)
16 BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c)
17 BIO_get_mem_ptr(BIO *b,BUF_MEM **pp)
18
19 BIO *BIO_new_mem_buf(void *buf, int len);
20
21=head1 DESCRIPTION
22
23BIO_s_mem() return the memory BIO method function.
24
25A memory BIO is a source/sink BIO which uses memory for its I/O. Data
26written to a memory BIO is stored in a BUF_MEM structure which is extended
27as appropriate to accommodate the stored data.
28
29Any data written to a memory BIO can be recalled by reading from it.
30Unless the memory BIO is read only any data read from it is deleted from
31the BIO.
32
33Memory BIOs support BIO_gets() and BIO_puts().
34
35If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying
36BUF_MEM structure is also freed.
37
38Calling BIO_reset() on a read write memory BIO clears any data in it. On a
39read only BIO it restores the BIO to its original state and the read only
40data can be read again.
41
42BIO_eof() is true if no data is in the BIO.
43
44BIO_ctrl_pending() returns the number of bytes currently stored.
45
46BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is
47empty. If the B<v> is zero then an empty memory BIO will return EOF (that is
48it will return zero and BIO_should_retry(b) will be false. If B<v> is non
49zero then it will return B<v> when it is empty and it will set the read retry
50flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal
51positive return value B<v> should be set to a negative value, typically -1.
52
53BIO_get_mem_data() sets B<pp> to a pointer to the start of the memory BIOs data
54and returns the total amount of data available. It is implemented as a macro.
55
56BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the
57close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE.
58It is a macro.
59
60BIO_get_mem_ptr() places the underlying BUF_MEM structure in B<pp>. It is
61a macro.
62
63BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>,
64if B<len> is -1 then the B<buf> is assumed to be null terminated and its
65length is determined by B<strlen>. The BIO is set to a read only state and
66as a result cannot be written to. This is useful when some data needs to be
67made available from a static area of memory in the form of a BIO. The
68supplied data is read directly from the supplied buffer: it is B<not> copied
69first, so the supplied area of memory must be unchanged until the BIO is freed.
70
71=head1 NOTES
72
73Writes to memory BIOs will always succeed if memory is available: that is
74their size can grow indefinitely.
75
76Every read from a read write memory BIO will remove the data just read with
77an internal copy operation, if a BIO contains a lot of data and it is
78read in small chunks the operation can be very slow. The use of a read only
79memory BIO avoids this problem. If the BIO must be read write then adding
80a buffering BIO to the chain will speed up the process.
81
82=head1 BUGS
83
84There should be an option to set the maximum size of a memory BIO.
85
86There should be a way to "rewind" a read write BIO without destroying
87its contents.
88
89The copying operation should not occur after every small read of a large BIO
90to improve efficiency.
91
92=head1 EXAMPLE
93
94Create a memory BIO and write some data to it:
95
96 BIO *mem = BIO_new(BIO_s_mem());
97 BIO_puts(mem, "Hello World\n");
98
99Create a read only memory BIO:
100
101 char data[] = "Hello World";
102 BIO *mem;
103 mem = BIO_new_mem_buf(data, -1);
104
105Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
106
107 BUF_MEM *bptr;
108 BIO_get_mem_ptr(mem, &bptr);
109 BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
110 BIO_free(mem);
111
112=cut
diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_null.pod b/src/lib/libssl/src/doc/crypto/BIO_s_null.pod
deleted file mode 100644
index 9f7d4ac46a..0000000000
--- a/src/lib/libssl/src/doc/crypto/BIO_s_null.pod
+++ /dev/null
@@ -1,35 +0,0 @@
1=pod
2
3=head1 NAME
4
5BIO_s_null - null data sink
6
7=head1 SYNOPSIS
8
9 #include <openssl/bio.h>
10
11 BIO_METHOD * BIO_s_null(void);
12
13=head1 DESCRIPTION
14
15BIO_s_null() returns the null sink BIO method. Data written to
16the null sink is discarded, reads return EOF.
17
18=head1 NOTES
19
20A null sink BIO behaves in a similar manner to the Unix /dev/null
21device.
22
23A null bio can be placed on the end of a chain to discard any data
24passed through it.
25
26A null sink is useful if, for example, an application wishes to digest some
27data by writing through a digest bio but not send the digested data anywhere.
28Since a BIO chain must normally include a source/sink BIO this can be achieved
29by adding a null sink BIO to the end of the chain
30
31=head1 RETURN VALUES
32
33BIO_s_null() returns the null sink BIO method.
34
35=cut
diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_socket.pod b/src/lib/libssl/src/doc/crypto/BIO_s_socket.pod
deleted file mode 100644
index 402aff26e2..0000000000
--- a/src/lib/libssl/src/doc/crypto/BIO_s_socket.pod
+++ /dev/null
@@ -1,61 +0,0 @@
1=pod
2
3=head1 NAME
4
5BIO_s_socket, BIO_new_socket - socket BIO
6
7=head1 SYNOPSIS
8
9 #include <openssl/bio.h>
10
11 BIO_METHOD *BIO_s_socket(void);
12
13 long BIO_set_fd(BIO *b, int fd, long close_flag);
14 long BIO_get_fd(BIO *b, int *c);
15
16 BIO *BIO_new_socket(int sock, int close_flag);
17
18=head1 DESCRIPTION
19
20BIO_s_socket() returns the socket BIO method. This is a wrapper
21round the platform's socket routines.
22
23BIO_read() and BIO_write() read or write the underlying socket.
24BIO_puts() is supported but BIO_gets() is not.
25
26If the close flag is set then the socket is shut down and closed
27when the BIO is freed.
28
29BIO_set_fd() sets the socket of BIO B<b> to B<fd> and the close
30flag to B<close_flag>.
31
32BIO_get_fd() places the socket in B<c> if it is not NULL, it also
33returns the socket. If B<c> is not NULL it should be of type (int *).
34
35BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>.
36
37=head1 NOTES
38
39Socket BIOs also support any relevant functionality of file descriptor
40BIOs.
41
42The reason for having separate file descriptor and socket BIOs is that on some
43platforms sockets are not file descriptors and use distinct I/O routines,
44Windows is one such platform. Any code mixing the two will not work on
45all platforms.
46
47BIO_set_fd() and BIO_get_fd() are macros.
48
49=head1 RETURN VALUES
50
51BIO_s_socket() returns the socket BIO method.
52
53BIO_set_fd() always returns 1.
54
55BIO_get_fd() returns the socket or -1 if the BIO has not been
56initialized.
57
58BIO_new_socket() returns the newly allocated BIO or NULL is an error
59occurred.
60
61=cut
diff --git a/src/lib/libssl/src/doc/crypto/BIO_set_callback.pod b/src/lib/libssl/src/doc/crypto/BIO_set_callback.pod
deleted file mode 100644
index 8e4e5900d9..0000000000
--- a/src/lib/libssl/src/doc/crypto/BIO_set_callback.pod
+++ /dev/null
@@ -1,105 +0,0 @@
1=pod
2
3=head1 NAME
4
5BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
6BIO_debug_callback - BIO callback functions
7
8=head1 SYNOPSIS
9
10 #include <openssl/bio.h>
11
12 #define BIO_set_callback(b,cb) ((b)->callback=(cb))
13 #define BIO_get_callback(b) ((b)->callback)
14 #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg))
15 #define BIO_get_callback_arg(b) ((b)->cb_arg)
16
17 long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,
18 long argl,long ret);
19
20 typedef long (*callback)(BIO *b, int oper, const char *argp,
21 int argi, long argl, long retvalue);
22
23=head1 DESCRIPTION
24
25BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback,
26they are both macros. The callback is called during most high level BIO
27operations. It can be used for debugging purposes to trace operations on
28a BIO or to modify its operation.
29
30BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be
31used to set and retrieve an argument for use in the callback.
32
33BIO_debug_callback() is a standard debugging callback which prints
34out information relating to each BIO operation. If the callback
35argument is set if is interpreted as a BIO to send the information
36to, otherwise stderr is used.
37
38callback() is the callback function itself. The meaning of each
39argument is described below.
40
41The BIO the callback is attached to is passed in B<b>.
42
43B<oper> is set to the operation being performed. For some operations
44the callback is called twice, once before and once after the actual
45operation, the latter case has B<oper> or'ed with BIO_CB_RETURN.
46
47The meaning of the arguments B<argp>, B<argi> and B<argl> depends on
48the value of B<oper>, that is the operation being performed.
49
50B<retvalue> is the return value that would be returned to the
51application if no callback were present. The actual value returned
52is the return value of the callback itself. In the case of callbacks
53called before the actual BIO operation 1 is placed in retvalue, if
54the return value is not positive it will be immediately returned to
55the application and the BIO operation will not be performed.
56
57The callback should normally simply return B<retvalue> when it has
58finished processing, unless if specifically wishes to modify the
59value returned to the application.
60
61=head1 CALLBACK OPERATIONS
62
63=over 4
64
65=item B<BIO_free(b)>
66
67callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the
68free operation.
69
70=item B<BIO_read(b, out, outl)>
71
72callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before
73the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
74after.
75
76=item B<BIO_write(b, in, inl)>
77
78callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before
79the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
80after.
81
82=item B<BIO_gets(b, out, outl)>
83
84callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before the operation and
85callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue) after.
86
87=item B<BIO_puts(b, in)>
88
89callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before
90the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
91after.
92
93=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)>
94
95callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and
96callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
97
98=back
99
100=head1 EXAMPLE
101
102The BIO_debug_callback() function is a good example, its source is
103in crypto/bio/bio_cb.c
104
105=cut
diff --git a/src/lib/libssl/src/doc/crypto/BIO_should_retry.pod b/src/lib/libssl/src/doc/crypto/BIO_should_retry.pod
deleted file mode 100644
index 3b7fc39997..0000000000
--- a/src/lib/libssl/src/doc/crypto/BIO_should_retry.pod
+++ /dev/null
@@ -1,112 +0,0 @@
1=pod
2
3=head1 NAME
4
5BIO_should_retry, BIO_should_read, BIO_should_write,
6BIO_should_io_special, BIO_retry_type,
7BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions
8
9=head1 SYNOPSIS
10
11 #include <openssl/bio.h>
12
13 #define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ)
14 #define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE)
15 #define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL)
16 #define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS)
17 #define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY)
18
19 #define BIO_FLAGS_READ 0x01
20 #define BIO_FLAGS_WRITE 0x02
21 #define BIO_FLAGS_IO_SPECIAL 0x04
22 #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)
23 #define BIO_FLAGS_SHOULD_RETRY 0x08
24
25 BIO * BIO_get_retry_BIO(BIO *bio, int *reason);
26 int BIO_get_retry_reason(BIO *bio);
27
28=head1 DESCRIPTION
29
30These functions determine why a BIO is not able to read or write data.
31They will typically be called after a failed BIO_read() or BIO_write()
32call.
33
34BIO_should_retry() is true if the call that produced this condition
35should then be retried at a later time.
36
37If BIO_should_retry() is false then the cause is an error condition.
38
39BIO_should_read() is true if the cause of the condition is that a BIO
40needs to read data.
41
42BIO_should_write() is true if the cause of the condition is that a BIO
43needs to read data.
44
45BIO_should_io_special() is true if some "special" condition, that is a
46reason other than reading or writing is the cause of the condition.
47
48BIO_retry_type() returns a mask of the cause of a retry condition
49consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>,
50B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of
51these.
52
53BIO_get_retry_BIO() determines the precise reason for the special
54condition, it returns the BIO that caused this condition and if
55B<reason> is not NULL it contains the reason code. The meaning of
56the reason code and the action that should be taken depends on
57the type of BIO that resulted in this condition.
58
59BIO_get_retry_reason() returns the reason for a special condition if
60passed the relevant BIO, for example as returned by BIO_get_retry_BIO().
61
62=head1 NOTES
63
64If BIO_should_retry() returns false then the precise "error condition"
65depends on the BIO type that caused it and the return code of the BIO
66operation. For example if a call to BIO_read() on a socket BIO returns
670 and BIO_should_retry() is false then the cause will be that the
68connection closed. A similar condition on a file BIO will mean that it
69has reached EOF. Some BIO types may place additional information on
70the error queue. For more details see the individual BIO type manual
71pages.
72
73If the underlying I/O structure is in a blocking mode almost all current
74BIO types will not request a retry, because the underlying I/O
75calls will not. If the application knows that the BIO type will never
76signal a retry then it need not call BIO_should_retry() after a failed
77BIO I/O call. This is typically done with file BIOs.
78
79SSL BIOs are the only current exception to this rule: they can request a
80retry even if the underlying I/O structure is blocking, if a handshake
81occurs during a call to BIO_read(). An application can retry the failed
82call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY
83on the underlying SSL structure.
84
85While an application may retry a failed non blocking call immediately
86this is likely to be very inefficient because the call will fail
87repeatedly until data can be processed or is available. An application
88will normally wait until the necessary condition is satisfied. How
89this is done depends on the underlying I/O structure.
90
91For example if the cause is ultimately a socket and BIO_should_read()
92is true then a call to select() may be made to wait until data is
93available and then retry the BIO operation. By combining the retry
94conditions of several non blocking BIOs in a single select() call
95it is possible to service several BIOs in a single thread, though
96the performance may be poor if SSL BIOs are present because long delays
97can occur during the initial handshake process.
98
99It is possible for a BIO to block indefinitely if the underlying I/O
100structure cannot process or return any data. This depends on the behaviour of
101the platforms I/O functions. This is often not desirable: one solution
102is to use non blocking I/O and use a timeout on the select() (or
103equivalent) call.
104
105=head1 BUGS
106
107The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:
108that is they cannot retry after a partial read or write. This is usually
109worked around by only passing the relevant data to ASN1 functions when
110the entire structure can be read or written.
111
112=cut