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