diff options
25 files changed, 2121 insertions, 1367 deletions
diff --git a/lib/libcrypto/man/BIO_push.3 b/lib/libcrypto/man/BIO_push.3 new file mode 100644 index 00000000000..848a09ba536 --- /dev/null +++ b/lib/libcrypto/man/BIO_push.3 @@ -0,0 +1,117 @@ +.Dd $Mdocdate: February 16 2015 $ +.Dt BIO_PUSH 3 +.Os +.Sh NAME +.Nm BIO_push , +.Nm BIO_pop +.Nd add and remove BIOs from a chain +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO * +.Fo BIO_push +.Fa "BIO *b" +.Fa "BIO *append" +.Fc +.Ft BIO * +.Fo BIO_pop +.Fa "BIO *b" +.Fc +.Sh DESCRIPTION +The +.Fn BIO_push +function appends the BIO +.Fa append +to +.Fa b +and returns +.Fa b . +.Pp +.Fn BIO_pop +removes the BIO +.Fa b +from a chain and returns the next BIO in the chain, or +.Dv NULL +if there is no next BIO. +The removed BIO then becomes a single BIO with no association with the +original chain, it can thus be freed or attached to a different chain. +.Sh RETURN VALUES +.Fn BIO_push +returns the beginning of the chain, +.Fa b . +.Pp +.Fn BIO_pop +returns the next BIO in the chain, or +.Dv NULL +if there is no next BIO. +.Sh NOTES +The names of these functions are perhaps a little misleading. +.Fn BIO_push +joins two BIO chains whereas +.Fn BIO_pop +deletes a single BIO from a chain, +the deleted BIO does not need to be at the end of a chain. +.Pp +The process of calling +.Fn BIO_push +and +.Fn BIO_pop +on a BIO may have additional consequences: +a control call is made to the affected BIOs. +Any effects will be noted in the descriptions of individual BIOs. +.Sh EXAMPLES +For these examples suppose +.Sy md1 +and +.Sy md2 +are digest BIOs, +.Sy b64 +is a base64 BIO and +.Sy f +is a file BIO. +.Pp +If the call +.Pp +.Dl BIO_push(b64, f); +.Pp +is made then the new chain will be +.Sy b64-f . +After making the calls +.Bd -literal -offset indent +BIO_push(md2, b64); +BIO_push(md1, md2); +.Ed +.Pp +the new chain is +.Sy md1-md2-b64-f . +Data written to +.Sy md1 +will be digested +by +.Sy md1 +and +.Sy md2 , +.Sy base64 +encoded and written to +.Sy f . +.Pp +It should be noted that reading causes data to pass +in the reverse direction, that is data is read from +.Sy f , +base64 +.Sy decoded +and digested +by +.Sy md1 +and +.Sy md2 . +If this call is made: +.Pp +.Dl BIO_pop(md2); +.Pp +The call will return +.Sy b64 +and the new chain will be +.Sy md1-b64-f Ns ; +data can be written to +.Sy md1 +as before. diff --git a/lib/libcrypto/man/BIO_read.3 b/lib/libcrypto/man/BIO_read.3 new file mode 100644 index 00000000000..3114ab3da41 --- /dev/null +++ b/lib/libcrypto/man/BIO_read.3 @@ -0,0 +1,115 @@ +.Dd $Mdocdate: February 16 2015 $ +.Dt BIO_READ 3 +.Os +.Sh NAME +.Nm BIO_read , +.Nm BIO_write , +.Nm BIO_gets , +.Nm BIO_puts +.Nd BIO I/O functions +.Sh SYNOPSIS +.In openssl/bio.h +.Ft int +.Fo BIO_read +.Fa "BIO *b" +.Fa "void *buf" +.Fa "int len" +.Fc +.Ft int +.Fo BIO_gets +.Fa "BIO *b" +.Fa "char *buf" +.Fa "int size" +.Fc +.Ft int +.Fo BIO_write +.Fa "BIO *b" +.Fa "const void *buf" +.Fa "int len" +.Fc +.Ft int +.Fo BIO_puts +.Fa "BIO *b" +.Fa "const char *buf" +.Fc +.Sh DESCRIPTION +.Fn BIO_read +attempts to read +.Fa len +bytes from BIO +.Fa b +and places the data in +.Fa buf . +.Pp +.Fn BIO_gets +performs the BIOs "gets" operation and places the data in +.Fa buf . +Usually this operation will attempt to read a line of data +from the BIO of maximum length +.Fa len . +There are exceptions to this however, for example +.Fn BIO_gets +on a digest BIO will calculate and return the digest +and other BIOs may not support +.Fn BIO_gets +at all. +.Pp +.Fn BIO_write +attempts to write +.Fa len +bytes from +.Fa buf +to BIO +.Fa b . +.Pp +.Fn BIO_puts +attempts to write a null terminated string +.Fa buf +to BIO +.Fa b . +.Sh RETURN VALUES +All these functions return either the amount of data successfully +read or written (if the return value is positive) or that no data +was successfully read or written if the result is 0 or -1. +If the return value is -2, then the operation is not implemented +in the specific BIO type. +.Sh NOTES +A 0 or -1 return is not necessarily an indication of an error. +In particular when the source/sink is non-blocking or of a certain type +it may merely be an indication that no data is currently available and that +the application should retry the operation later. +.Pp +One technique sometimes used with blocking sockets +is to use a system call (such as +.Xr select 2 , +.Xr poll 2 +or equivalent) to determine when data is available and then call +.Xr read 3 +to read the data. +The equivalent with BIOs (that is call +.Xr select 2 +on the underlying I/O structure and then call +.Fn BIO_read +to read the data) should +.Em not +be used because a single call to +.Fn BIO_read +can cause several reads (and writes in the case of SSL BIOs) +on the underlying I/O structure and may block as a result. +Instead +.Xr select 2 +(or equivalent) should be combined with non blocking I/O +so successive reads will request a retry instead of blocking. +.Pp +See +.Xr BIO_should_retry 3 +for details of how to determine the cause of a retry and other I/O issues. +.Pp +If the +.Fn BIO_gets +function is not supported by a BIO then it is possible to +work around this by adding a buffering BIO +.Xr BIO_f_buffer 3 +to the chain. +.Sh SEE ALSO +.Xr BIO_should_retry 3 diff --git a/lib/libcrypto/man/BIO_s_accept.3 b/lib/libcrypto/man/BIO_s_accept.3 new file mode 100644 index 00000000000..f5adfcc07ca --- /dev/null +++ b/lib/libcrypto/man/BIO_s_accept.3 @@ -0,0 +1,279 @@ +.Dd $Mdocdate: February 16 2015 $ +.Dt BIO_S_ACCEPT 3 +.Os +.Sh NAME +.Nm BIO_s_accept , +.Nm BIO_set_accept_port , +.Nm BIO_get_accept_port , +.Nm BIO_new_accept , +.Nm BIO_set_nbio_accept , +.Nm BIO_set_accept_bios , +.Nm BIO_set_bind_mode , +.Nm BIO_get_bind_mode , +.Nm BIO_do_accept +.Nd accept BIO +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO_METHOD * +.Fo BIO_s_accept +.Fa void +.Fc +.Ft long +.Fo BIO_set_accept_port +.Fa "BIO *b" +.Fa "char *name" +.Fc +.Ft char * +.Fo BIO_get_accept_port +.Fa "BIO *b" +.Fc +.Ft BIO * +.Fo BIO_new_accept +.Fa "char *host_port" +.Fc +.Ft long +.Fo BIO_set_nbio_accept +.Fa "BIO *b" +.Fa "int n" +.Fc +.Ft long +.Fo BIO_set_accept_bios +.Fa "BIO *b" +.Fa "char *bio" +.Fc +.Ft long +.Fo BIO_set_bind_mode +.Fa "BIO *b" +.Fa "long mode" +.Fc +.Ft long +.Fo BIO_get_bind_mode +.Fa "BIO *b" +.Fa "long dummy" +.Fc +.Fd #define BIO_BIND_NORMAL 0 +.Fd #define BIO_BIND_REUSEADDR_IF_UNUSED 1 +.Fd #define BIO_BIND_REUSEADDR 2 +.Ft int +.Fo BIO_do_accept +.Fa "BIO *b" +.Fc +.Sh DESCRIPTION +.Fn BIO_s_accept +returns the accept BIO method. +This is a wrapper round the platform's TCP/IP socket accept routines. +.Pp +Using accept BIOs, TCP/IP connections can be accepted +and data transferred using only BIO routines. +In this way any platform specific operations +are hidden by the BIO abstraction. +.Pp +Read and write operations on an accept BIO +will perform I/O on the underlying connection. +If no connection is established and the port (see below) is set up +properly then the BIO waits for an incoming connection. +.Pp +Accept BIOs support +.Xr BIO_puts 3 +but not +.Xr BIO_gets 3 . +.Pp +If the close flag is set on an accept BIO, then any active +connection on that chain is shutdown and the socket closed when +the BIO is freed. +.Pp +Calling +.Xr BIO_reset 3 +on a accept BIO will close any active connection and reset the BIO +into a state where it awaits another incoming connection. +.Pp +.Xr BIO_get_fd 3 +and +.Xr BIO_set_fd 3 +can be called to retrieve or set the accept socket. +See +.Xr BIO_s_fd 3 . +.Pp +.Fn BIO_set_accept_port +uses the string +.Fa name +to set the accept port. +The port is represented as a string of the form +.Ar host : Ns Ar port , +where +.Ar host +is the interface to use and +.Ar port +is the port. +Either or both values can be +.Qq * +which is interpreted as meaning any interface or port respectively. +.Ar port +has the same syntax as the port specified in +.Xr BIO_set_conn_port 3 +for connect BIOs. +It can be a numerical port string or a string to lookup using +.Xr getservbyname 3 +and a string table. +.Pp +.Fn BIO_new_accept +combines +.Xr BIO_new 3 +and +.Fn BIO_set_accept_port +into a single call. +It creates a new accept BIO with port +.Fa host_port . +.Pp +.Fn BIO_set_nbio_accept +sets the accept socket to blocking mode (the default) if +.Fa n +is 0 or non blocking mode if +.Fa n +is 1. +.Pp +.Fn BIO_set_accept_bios +can be used to set a chain of BIOs which will be duplicated +and prepended to the chain when an incoming connection is received. +This is useful if, for example, a buffering or SSL BIO +is required for each connection. +The chain of BIOs must not be freed after this call, +they will be automatically freed when the accept BIO is freed. +.Pp +.Fn BIO_set_bind_mode +and +.Fn BIO_get_bind_mode +set and retrieve the current bind mode. +If +.Dv BIO_BIND_NORMAL Pq the default +is set, then another socket cannot be bound to the same port. +If +.Dv BIO_BIND_REUSEADDR +is set, then other sockets can bind to the same port. +If +.Dv BIO_BIND_REUSEADDR_IF_UNUSED +is set, then an attempt is first made to use +.Dv BIO_BIN_NORMAL ; +if this fails and the port is not in use, +then a second attempt is made using +.Dv BIO_BIND_REUSEADDR . +.Pp +.Fn BIO_do_accept +serves two purposes. +When it is first called, after the accept BIO has been setup, +it will attempt to create the accept socket and bind an address to it. +Second and subsequent calls to +.Fn BIO_do_accept +will await an incoming connection, or request a retry in non blocking mode. +.Sh NOTES +When an accept BIO is at the end of a chain, it will await an +incoming connection before processing I/O calls. +When an accept BIO is not at then end of a chain, +it passes I/O calls to the next BIO in the chain. +.Pp +When a connection is established a new socket BIO is created +for the connection and appended to the chain. +That is the chain is now accept->socket. +This effectively means that attempting I/O on an initial accept +socket will await an incoming connection then perform I/O on it. +.Pp +If any additional BIOs have been set using +.Fn BIO_set_accept_bios , +then they are placed between the socket and the accept BIO, +that is the chain will be accept->otherbios->socket. +.Pp +If a server wishes to process multiple connections (as is normally +the case), then the accept BIO must be made available for further +incoming connections. +This can be done by waiting for a connection and then calling: +.Pp +.Dl connection = BIO_pop(accept); +.Pp +After this call, +.Sy connection +will contain a BIO for the recently established connection and +.Sy accept +will now be a single BIO again which can be used +to await further incoming connections. +If no further connections will be accepted, the +.Sy accept +can be freed using +.Xr BIO_free 3 . +.Pp +If only a single connection will be processed, +it is possible to perform I/O using the accept BIO itself. +This is often undesirable however because the accept BIO +will still accept additional incoming connections. +This can be resolved by using +.Xr BIO_pop 3 +(see above) and freeing up the accept BIO after the initial connection. +.Pp +If the underlying accept socket is non-blocking and +.Fn BIO_do_accept +is called to await an incoming connection, it is possible for +.Xr BIO_should_io_special 3 +with the reason +.Dv BIO_RR_ACCEPT . +If this happens, then it is an indication that an accept attempt +would block: the application should take appropriate action +to wait until the underlying socket has accepted a connection +and retry the call. +.Pp +.Fn BIO_set_accept_port , +.Fn BIO_get_accept_port , +.Fn BIO_set_nbio_accept , +.Fn BIO_set_accept_bios , +.Fn BIO_set_bind_mode , +.Fn BIO_get_bind_mode , +and +.Fn BIO_do_accept +are macros. +.Sh EXAMPLES +This example accepts two connections on port 4444, +sends messages down each and finally closes both down. +.Bd -literal -offset 2n +BIO *abio, *cbio, *cbio2; +ERR_load_crypto_strings(); +abio = BIO_new_accept("4444"); + +/* First call to BIO_accept() sets up accept BIO */ +if (BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error setting up accept\en"); + ERR_print_errors_fp(stderr); + exit(0); +} + +/* Wait for incoming connection */ +if (BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error accepting connection\en"); + ERR_print_errors_fp(stderr); + exit(0); +} +fprintf(stderr, "Connection 1 established\en"); + +/* Retrieve BIO for connection */ +cbio = BIO_pop(abio); + +BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\en"); +fprintf(stderr, "Sent out data on connection 1\en"); + +/* Wait for another connection */ +if (BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error accepting connection\en"); + ERR_print_errors_fp(stderr); + exit(0); +} +fprintf(stderr, "Connection 2 established\en"); + +/* Close accept BIO to refuse further connections */ +cbio2 = BIO_pop(abio); +BIO_free(abio); + +BIO_puts(cbio2, "Connection 2: Sending out Data on second\en"); +fprintf(stderr, "Sent out data on connection 2\en"); +BIO_puts(cbio, "Connection 1: Second connection established\en"); + +/* Close the two established connections */ +BIO_free(cbio); +BIO_free(cbio2); +.Ed diff --git a/lib/libcrypto/man/BIO_s_bio.3 b/lib/libcrypto/man/BIO_s_bio.3 new file mode 100644 index 00000000000..af7bdabd335 --- /dev/null +++ b/lib/libcrypto/man/BIO_s_bio.3 @@ -0,0 +1,295 @@ +.Dd $Mdocdate: February 16 2015 $ +.Dt BIO_S_BIO 3 +.Os +.Sh NAME +.Nm BIO_s_bio , +.Nm BIO_make_bio_pair , +.Nm BIO_destroy_bio_pair , +.Nm BIO_shutdown_wr , +.Nm BIO_set_write_buf_size , +.Nm BIO_get_write_buf_size , +.Nm BIO_new_bio_pair , +.Nm BIO_get_write_guarantee , +.Nm BIO_ctrl_get_write_guarantee , +.Nm BIO_get_read_request , +.Nm BIO_ctrl_get_read_request , +.Nm BIO_ctrl_reset_read_request +.Nd BIO pair BIO +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO_METHOD * +.Fo BIO_s_bio +.Fa void +.Fc +.Bd -unfilled +#define BIO_make_bio_pair(b1, b2) \e + (int)BIO_ctrl(b1, BIO_C_MAKE_BIO_PAIR, 0, b2) +#define BIO_destroy_bio_pair(b) \e + (int)BIO_ctrl(b, BIO_C_DESTROY_BIO_PAIR, 0, NULL) +#define BIO_shutdown_wr(b) \e + (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL) +#define BIO_set_write_buf_size(b, size) \e + (int)BIO_ctrl(b, BIO_C_SET_WRITE_BUF_SIZE, size, NULL) +#define BIO_get_write_buf_size(b, size) \e + (size_t)BIO_ctrl(b, BIO_C_GET_WRITE_BUF_SIZE, size, NULL) +.Ed +.Pp +.Ft int +.Fo BIO_new_bio_pair +.Fa "BIO **bio1" +.Fa "size_t writebuf1" +.Fa "BIO **bio2" +.Fa "size_t writebuf2" +.Fc +.Bd -unfilled +#define BIO_get_write_guarantee(b) \e + (int)BIO_ctrl(b, BIO_C_GET_WRITE_GUARANTEE, 0, NULL) +.Ed +.Pp +.Ft size_t +.Fo BIO_ctrl_get_write_guarantee +.Fa "BIO *b" +.Fc +.Bd -unfilled +#define BIO_get_read_request(b) \e + (int)BIO_ctrl(b, BIO_C_GET_READ_REQUEST, 0, NULL) +.Ed +.Pp +.Ft size_t +.Fo BIO_ctrl_get_read_request +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_ctrl_reset_read_request +.Fa "BIO *b" +.Fc +.Sh DESCRIPTION +.Fn BIO_s_bio +returns the method for a BIO pair. +A BIO pair is a pair of source/sink BIOs where data written to either +half of the pair is buffered and can be read from the other half. +Both halves must usually be handled by the same application thread +since no locking is done on the internal data structures. +.Pp +Since BIO chains typically end in a source/sink BIO, +it is possible to make this one half of a BIO pair and +have all the data processed by the chain under application control. +.Pp +One typical use of BIO pairs is +to place TLS/SSL I/O under application control. +This can be used when the application wishes to use a non standard +transport for TLS/SSL or the normal socket routines are inappropriate. +.Pp +Calls to +.Xr BIO_read 3 +will read data from the buffer or request a retry if no data is available. +.Pp +Calls to +.Xr BIO_write 3 +will place data in the buffer or request a retry if the buffer is full. +.Pp +The standard calls +.Xr BIO_ctrl_pending 3 +and +.Xr BIO_ctrl_wpending 3 +can be used to determine the amount of pending data +in the read or write buffer. +.Pp +.Xr BIO_reset 3 +clears any data in the write buffer. +.Pp +.Fn BIO_make_bio_pair +joins two separate BIOs into a connected pair. +.Pp +.Fn BIO_destroy_pair +destroys the association between two connected BIOs. +Freeing up any half of the pair will automatically destroy the association. +.Pp +.Fn BIO_shutdown_wr +is used to close down a BIO +.Fa b . +After this call no further writes on BIO +.Fa b +are allowed; they will return an error. +Reads on the other half of the pair will return any pending data +or EOF when all pending data has been read. +.Pp +.Fn BIO_set_write_buf_size +sets the write buffer size of BIO +.Fa b +to +.Fa size . +If the size is not initialized a default value is used. +This is currently 17K, sufficient for a maximum size TLS record. +.Pp +.Fn BIO_get_write_buf_size +returns the size of the write buffer. +.Pp +.Fn BIO_new_bio_pair +combines the calls to +.Xr BIO_new 3 , +.Fn BIO_make_bio_pair +and +.Fn BIO_set_write_buf_size +to create a connected pair of BIOs +.Fa bio1 +and +.Fa bio2 +with write buffer sizes +.Fa writebuf1 +and +.Fa writebuf2 . +If either size is zero, then the default size is used. +.Fn BIO_new_bio_pair +does not check whether +.Fa bio1 +or +.Fa bio2 +do point to some other BIO, the values are overwritten, +.Xr BIO_free 3 +is not called. +.Pp +.Fn BIO_get_write_guarantee +and +.Fn BIO_ctrl_get_write_guarantee +return the maximum length of data +that can be currently written to the BIO. +Writes larger than this value will return a value from +.Xr BIO_write 3 +less than the amount requested or if the buffer is full request a retry. +.Fn BIO_ctrl_get_write_guarantee +is a function whereas +.Fn BIO_get_write_guarantee +is a macro. +.Pp +.Fn BIO_get_read_request +and +.Fn BIO_ctrl_get_read_request +return the amount of data requested, or the buffer size if it is less, +if the last read attempt at the other half of the BIO pair failed +due to an empty buffer. +This can be used to determine how much data should be +written to the BIO so the next read will succeed: +this is most useful in TLS/SSL applications where the amount of +data read is usually meaningful rather than just a buffer size. +After a successful read this call will return zero. +It also will return zero once new data has been written +satisfying the read request or part of it. +Note that +.Fn BIO_get_read_request +never returns an amount larger than that returned by +.Fn BIO_get_write_guarantee . +.Pp +.Fn BIO_ctrl_reset_read_request +can also be used to reset the value returned by +.Fn BIO_get_read_request +to zero. +.Sh RETURN VALUES +.Fn BIO_new_bio_pair +returns 1 on success, with the new BIOs available in +.Fa bio1 +and +.Fa bio2 , +or 0 on failure, with NULL pointers stored into the locations for +.Fa bio1 +and +.Fa bio2 . +Check the error stack for more information. +.\" XXX More return values need to be added here. +.Sh NOTES +Both halves of a BIO pair should be freed. +Even if one half is implicitly freed due to a +.Xr BIO_free_all 3 +or +.Xr SSL_free 3 +call, the other half still needs to be freed. +.Pp +When used in bidirectional applications (such as TLS/SSL) +care should be taken to flush any data in the write buffer. +This can be done by calling +.Xr BIO_pending 3 +on the other half of the pair and, if any data is pending, +reading it and sending it to the underlying transport. +This must be done before any normal processing (such as calling +.Xr select 2 ) +due to a request and +.Xr BIO_should_read 3 +being true. +.Pp +To see why this is important, +consider a case where a request is sent using +.Xr BIO_write 3 +and a response read with +.Xr BIO_read 3 , +this can occur during an TLS/SSL handshake for example. +.Xr BIO_write 3 +will succeed and place data in the write buffer. +.Xr BIO_read 3 +will initially fail and +.Xr BIO_should_read 3 +will be true. +If the application then waits for data to become available +on the underlying transport before flushing the write buffer, +it will never succeed because the request was never sent. +.Sh EXAMPLE +The BIO pair can be used to have full control +over the network access of an application. +The application can call +.Xr select 2 +on the socket as required without having to go through the SSL-interface. +.Bd -literal -offset 2n +BIO *internal_bio, *network_bio; +\&... +BIO_new_bio_pair(internal_bio, 0, network_bio, 0); +SSL_set_bio(ssl, internal_bio, internal_bio); +SSL_operations(); +\&... + +application | TLS-engine + | | + +----------> SSL_operations() + | /\e || + | || \e/ + | BIO-pair (internal_bio) + +----------< BIO-pair (network_bio) + | | + socket | + +\&... +SSL_free(ssl); /* implicitly frees internal_bio */ +BIO_free(network_bio); +\&... +.Ed +.Pp +As the BIO pair will only buffer the data and never directly access +the connection, it behaves non-blocking and will return as soon as +the write buffer is full or the read buffer is drained. +Then the application has to flush the write buffer +and/or fill the read buffer. +.Pp +Use +.Xr BIO_ctrl_pending 3 +to find out whether data is buffered in the BIO +and must be transfered to the network. +Use +.Fn BIO_ctrl_get_read_request +to find out how many bytes must be written into the buffer before the +.Xr SSL_operation 3 +can successfully be continued. +.Sh SEE ALSO +.Xr bio 3 , +.Xr BIO_read 3 , +.Xr BIO_should_retry 3 , +.Xr ssl 3 , +.Xr SSL_set_bio 3 +.Sh CAVEATS +As the data is buffered, +.Xr SSL_operation 3 +may return with an +.Dv ERROR_SSL_WANT_READ +condition, but there is still data in the write buffer. +An application must not rely on the error value of +.Xr SSL_operation 3 +but must assure that the write buffer is always flushed first. +Otherwise a deadlock may occur as the peer might be waiting +for the data before being able to continue. diff --git a/lib/libcrypto/man/BIO_s_connect.3 b/lib/libcrypto/man/BIO_s_connect.3 new file mode 100644 index 00000000000..960400e8536 --- /dev/null +++ b/lib/libcrypto/man/BIO_s_connect.3 @@ -0,0 +1,332 @@ +.Dd $Mdocdate: February 16 2015 $ +.Dt BIO_S_CONNECT 3 +.Os +.Sh NAME +.Nm BIO_s_connect , +.Nm BIO_new_connect , +.Nm BIO_set_conn_hostname , +.Nm BIO_set_conn_port , +.Nm BIO_set_conn_ip , +.Nm BIO_set_conn_int_port , +.Nm BIO_get_conn_hostname , +.Nm BIO_get_conn_port , +.Nm BIO_get_conn_ip , +.Nm BIO_get_conn_int_port , +.Nm BIO_set_nbio , +.Nm BIO_do_connect +.Nd connect BIO +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO_METHOD * +.Fo BIO_s_connect +.Fa void +.Fc +.Ft BIO * +.Fo BIO_new_connect +.Fa "char *name" +.Fc +.Ft long +.Fo BIO_set_conn_hostname +.Fa "BIO *b" +.Fa "char *name" +.Fc +.Ft long +.Fo BIO_set_conn_port +.Fa "BIO *b" +.Fa "char *port" +.Fc +.Ft long +.Fo BIO_set_conn_ip +.Fa "BIO *b" +.Fa "char *ip" +.Fc +.Ft long +.Fo BIO_set_conn_int_port +.Fa "BIO *b" +.Fa "char *port" +.Fc +.Ft char * +.Fo BIO_get_conn_hostname +.Fa "BIO *b" +.Fc +.Ft char * +.Fo BIO_get_conn_port +.Fa "BIO *b" +.Fc +.Ft char * +.Fo BIO_get_conn_ip +.Fa "BIO *b" +.Fa "dummy" +.Fc +.Ft long +.Fo BIO_get_conn_int_port +.Fa "BIO *b" +.Fa "int port" +.Fc +.Ft long +.Fo BIO_set_nbio +.Fa "BIO *b" +.Fa "long n" +.Fc +.Ft int +.Fo BIO_do_connect +.Fa "BIO *b" +.Fc +.Sh DESCRIPTION +.Fn BIO_s_connect +returns the connect BIO method. +This is a wrapper around the platform's TCP/IP socket connection routines. +.Pp +Using connect BIOs, TCP/IP connections can be made and data +transferred using only BIO routines. +In this way any platform specific operations +are hidden by the BIO abstraction. +.Pp +Read and write operations on a connect BIO will perform I/O +on the underlying connection. +If no connection is established and the port and hostname (see below) +is set up properly, then a connection is established first. +.Pp +Connect BIOs support +.Xr BIO_puts 3 +but not +.Xr BIO_gets 3 . +.Pp +If the close flag is set on a connect BIO, then any active connection +is shutdown and the socket closed when the BIO is freed. +.Pp +Calling +.Xr BIO_reset 3 +on a connect BIO will close any active connection and reset the BIO +into a state where it can connect to the same host again. +.Pp +.Xr BIO_get_fd 3 +places the underlying socket in +.Fa c +if it is not +.Dv NULL , +it also returns the socket. +If +.Fa c +is not +.Dv NULL +it should be of type +.Vt "int *" . +.Pp +.Fn BIO_set_conn_hostname +uses the string +.Fa name +to set the hostname. +The hostname can be an IP address. +The hostname can also include the port in the form +.Ar hostname : Ns Ar port . +It is also acceptable to use the forms +.Ar hostname Ns / Ns Pa any/other/path +or +.Ar hostname : Ns Ar port Ns / Ns Pa any/other/path . +.Pp +.Fn BIO_set_conn_port +sets the port to +.Fa port . +.Fa port +can be the numerical form or a string such as +.Cm http . +A string will be looked up first using +.Xr getservbyname 3 +on the host platform, but if that fails +a built-in table of port names will be used. +Currently the list is +.Cm http , +.Cm telnet , +.Cm socks , +.Cm https , +.Cm ssl , +.Cm ftp , +.Cm gopher , +and +.Cm wais . +.Pp +.Fn BIO_set_conn_ip +sets the IP address to +.Fa ip +using binary form, that is four bytes specifying the IP address +in big-endian form. +.Pp +.Fn BIO_set_conn_int_port +sets the port using +.Fa port . +.Fa port +should +be of type +.Vt "int *" . +.Pp +.Fn BIO_get_conn_hostname +returns the hostname of the connect BIO or +.Dv NULL +if the BIO is initialized but no hostname is set. +This return value is an internal pointer which should not be modified. +.Pp +.Fn BIO_get_conn_port +returns the port as a string. +.Pp +.Fn BIO_get_conn_ip +returns the IP address in binary form. +.Pp +.Fn BIO_get_conn_int_port +returns the port as an +.Vt int . +.Pp +.Fn BIO_set_nbio +sets the non blocking I/O flag to +.Fa n . +If +.Fa n +is zero then blocking I/O is set. +If +.Fa n +is 1 then non blocking I/O is set. +Blocking I/O is the default. +The call to +.Fn BIO_set_nbio +should be made before the connection is established +because non blocking I/O is set during the connect process. +.Pp +.Fn BIO_new_connect +combines +.Xr BIO_new 3 +and +.Fn BIO_set_conn_hostname +into a single call. +It creates a new connect BIO with +.Fa name . +.Pp +.Fn BIO_do_connect +attempts to connect the supplied BIO. +It returns 1 if the connection was established successfully. +A zero or negative value is returned if the connection +could not be established. +The call +.Xr BIO_should_retry 3 +should be used for non blocking connect BIOs +to determine if the call should be retried. +.Sh NOTES +If blocking I/O is set then a non positive return value from any +I/O call is caused by an error condition, although a zero return +will normally mean that the connection was closed. +.Pp +If the port name is supplied as part of the host name then this will +override any value set with +.Fn BIO_set_conn_port . +This may be undesirable if the application does not wish to allow +connection to arbitrary ports. +This can be avoided by checking for the presence of the +.Sq \&: +character in the passed hostname and either indicating an error +or truncating the string at that point. +.Pp +The values returned by +.Fn BIO_get_conn_hostname , +.Fn BIO_get_conn_port , +.Fn BIO_get_conn_ip , +and +.Fn BIO_get_conn_int_port +are updated when a connection attempt is made. +Before any connection attempt the values returned +are those set by the application itself. +.Pp +Applications do not have to call +.Fn BIO_do_connect +but may wish to do so to separate the connection process +from other I/O processing. +.Pp +If non-blocking I/O is set, +then retries will be requested as appropriate. +.Pp +It addition to +.Xr BIO_should_read 3 +and +.Xr BIO_should_write 3 +it is also possible for +.Xr BIO_should_io_special 3 +to be true during the initial connection process with the reason +.Dv BIO_RR_CONNECT . +If this is returned, it is an indication +that a connection attempt would block. +The application should then take appropriate action to wait +until the underlying socket has connected and retry the call. +.Pp +.Fn BIO_set_conn_hostname , +.Fn BIO_set_conn_port , +.Fn BIO_set_conn_ip , +.Fn BIO_set_conn_int_port , +.Fn BIO_get_conn_hostname , +.Fn BIO_get_conn_port , +.Fn BIO_get_conn_ip , +.Fn BIO_get_conn_int_port , +.Fn BIO_set_nbio , +and +.Fn BIO_do_connect +are macros. +.Sh RETURN VALUES +.Fn BIO_s_connect +returns the connect BIO method. +.Pp +.Xr BIO_get_fd 3 +returns the socket or -1 if the BIO has not been initialized. +.Pp +.Fn BIO_set_conn_hostname , +.Fn BIO_set_conn_port , +.Fn BIO_set_conn_ip , +and +.Fn BIO_set_conn_int_port +always return 1. +.Pp +.Fn BIO_get_conn_hostname +returns the connected hostname or +.Dv NULL +if none is set. +.Pp +.Fn BIO_get_conn_port +returns a string representing the connected port or +.Dv NULL +if not set. +.Pp +.Fn BIO_get_conn_ip +returns a pointer to the connected IP address in binary form +or all zeros if not set. +.Pp +.Fn BIO_get_conn_int_port +returns the connected port or 0 if none was set. +.Pp +.Fn BIO_set_nbio +always returns 1. +.Pp +.Fn BIO_do_connect +returns 1 if the connection was successfully +established and 0 or -1 if the connection failed. +.Sh EXAMPLES +This example connects to a webserver on the local host and attempts +to retrieve a page and copy the result to standard output. +.Bd -literal -offset 2n +BIO *cbio, *out; +int len; +char tmpbuf[1024]; + +ERR_load_crypto_strings(); +cbio = BIO_new_connect("localhost:http"); +out = BIO_new_fp(stdout, BIO_NOCLOSE); +if (BIO_do_connect(cbio) <= 0) { + fprintf(stderr, "Error connecting to server\en"); + ERR_print_errors_fp(stderr); + /* whatever ... */ +} +BIO_puts(cbio, "GET / HTTP/1.0\en\en"); +for(;;) { + len = BIO_read(cbio, tmpbuf, 1024); + if (len <= 0) + break; + BIO_write(out, tmpbuf, len); +} +BIO_free(cbio); +BIO_free(out); +.Ed diff --git a/lib/libcrypto/man/BIO_s_fd.3 b/lib/libcrypto/man/BIO_s_fd.3 new file mode 100644 index 00000000000..3d6a2a3ca92 --- /dev/null +++ b/lib/libcrypto/man/BIO_s_fd.3 @@ -0,0 +1,137 @@ +.Dd $Mdocdate: February 16 2015 $ +.Dt BIO_S_FD 3 +.Os +.Sh NAME +.Nm BIO_s_fd , +.Nm BIO_set_fd , +.Nm BIO_get_fd , +.Nm BIO_new_fd +.Nd file descriptor BIO +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO_METHOD * +.Fo BIO_s_fd +.Fa "void" +.Fc +.Fd #define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd) +.Fd #define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c) +.Ft BIO * +.Fo BIO_new_fd +.Fa "int fd" +.Fa "int close_flag" +.Fc +.Sh DESCRIPTION +.Fn BIO_s_fd +returns the file descriptor BIO method. +This is a wrapper around the platform's file descriptor routines such as +.Xr read 2 +and +.Xr write 2 . +.Pp +.Xr BIO_read 3 +and +.Xr BIO_write 3 +read or write the underlying descriptor. +.Xr BIO_puts 3 +is supported but +.Xr BIO_gets 3 +is not. +.Pp +If the close flag is set, +.Xr close 2 +is called on the underlying file descriptor when the BIO is freed. +.Pp +.Xr BIO_reset 3 +attempts to set the file pointer to the start of the file using +.Fn lseek fd 0 0 . +.Pp +.Xr BIO_seek 3 +sets the file pointer to position +.Fa ofs +from start of file using +.Fn lseek fd ofs 0 . +.Pp +.Xr BIO_tell 3 +returns the current file position by calling +.Fn lseek fd 0 1 . +.Pp +.Fn BIO_set_fd +sets the file descriptor of BIO +.Fa b +to +.Fa fd +and the close flag to +.Fa c . +.Pp +.Fn BIO_get_fd +places the file descriptor in +.Fa c +if it is not +.Dv NULL , +it also returns the file descriptor. +If +.Fa c +is not +.Dv NULL , +it should be of type +.Vt "int *" . +.Pp +.Fn BIO_new_fd +returns a file descriptor BIO using +.Fa fd +and +.Fa close_flag . +.Sh NOTES +The behaviour of +.Xr BIO_read 3 +and +.Xr BIO_write 3 +depends on the behavior of the platform's +.Xr read 2 +and +.Xr write 2 +calls on the descriptor. +If the underlying file descriptor is in a non blocking mode, +then the BIO will behave in the manner described in the +.Xr BIO_read 3 +and +.Xr BIO_should_retry 3 +manual pages. +.Pp +File descriptor BIOs should not be used for socket I/O. +Use socket BIOs instead. +.Sh RETURN VALUES +.Fn BIO_s_fd +returns the file descriptor BIO method. +.Pp +.Xr BIO_reset 3 +returns zero for success and -1 if an error occurred. +.Xr BIO_seek 3 +and +.Xr BIO_tell 3 +return the current file position or -1 if an error occurred. +These values reflect the underlying +.Xr lseek 2 +behaviour. +.Pp +.Fn BIO_set_fd +always returns 1. +.Pp +.Fn BIO_get_fd +returns the file descriptor or -1 if the BIO has not been initialized. +.Pp +.Fn BIO_new_fd +returns the newly allocated BIO or +.Dv NULL +if an error occurred. +.Sh EXAMPLE +This is a file descriptor BIO version of "Hello World": +.Bd -literal -offset indent +BIO *out; +out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE); +BIO_printf(out, "Hello World\en"); +BIO_free(out); +.Ed +.Sh SEE ALSO +.Xr BIO_read 3 , +.Xr BIO_seek 3 diff --git a/lib/libcrypto/man/BIO_s_file.3 b/lib/libcrypto/man/BIO_s_file.3 new file mode 100644 index 00000000000..c7075a3fb7c --- /dev/null +++ b/lib/libcrypto/man/BIO_s_file.3 @@ -0,0 +1,248 @@ +.Dd $Mdocdate: February 16 2015 $ +.Dt BIO_S_FILE 3 +.Os +.Sh NAME +.Nm BIO_s_file , +.Nm BIO_new_file , +.Nm BIO_new_fp , +.Nm BIO_set_fp , +.Nm BIO_get_fp , +.Nm BIO_read_filename , +.Nm BIO_write_filename , +.Nm BIO_append_filename , +.Nm BIO_rw_filename +.Nd FILE bio +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO_METHOD * +.Fo BIO_s_file +.Fa void +.Fc +.Ft BIO * +.Fo BIO_new_file +.Fa "const char *filename" +.Fa "const char *mode" +.Fc +.Ft BIO * +.Fo BIO_new_fp +.Fa "FILE *stream" +.Fa "int flags" +.Fc +.Ft long +.Fo BIO_set_fp +.Fa "BIO *b" +.Fa "FILE *fp" +.Fa "int flags" +.Fc +.Ft long +.Fo BIO_get_fp +.Fa "BIO *b" +.Fa "FILE **fpp" +.Fc +.Ft int +.Fo BIO_read_filename +.Fa "BIO *b" +.Fa "char *name" +.Fc +.Ft int +.Fo BIO_write_filename +.Fa "BIO *b" +.Fa "char *name" +.Fc +.Ft int +.Fo BIO_append_filename +.Fa "BIO *b" +.Fa "char *name" +.Fc +.Ft int +.Fo BIO_rw_filename +.Fa "BIO *b" +.Fa "char *name" +.Fc +.Sh DESCRIPTION +.Fn BIO_s_file +returns the BIO file method. +As its name implies, it is a wrapper around the stdio +.Vt FILE +structure and it is a source/sink BIO. +.Pp +Calls to +.Xr BIO_read 3 +and +.Xr BIO_write 3 +read and write data to the underlying stream. +.Xr BIO_gets 3 +and +.Xr BIO_puts 3 +are supported on file BIOs. +.Pp +.Xr BIO_flush 3 +on a file BIO calls the +.Xr fflush 3 +function on the wrapped stream. +.Pp +.Xr BIO_reset 3 +attempts to change the file pointer to the start of file using +.Fn fseek stream 0 0 . +.Pp +.Xr BIO_seek 3 +sets the file pointer to position +.Fa ofs +from the start of the file using +.Fn fseek stream ofs 0 . +.Pp +.Xr BIO_eof 3 +calls +.Xr feof 3 . +.Pp +Setting the +.Dv BIO_CLOSE +flag calls +.Xr fclose 3 +on the stream when the BIO is freed. +.Pp +.Fn BIO_new_file +creates a new file BIO with mode +.Fa mode . +The meaning of +.Fa mode +is the same as for the stdio function +.Xr fopen 3 . +The +.Dv BIO_CLOSE +flag is set on the returned BIO. +.Pp +.Fn BIO_new_fp +creates a file BIO wrapping +.Fa stream . +Flags can be: +.Dv BIO_CLOSE , BIO_NOCLOSE Pq the close flag , +.Dv BIO_FP_TEXT +(sets the underlying stream to text mode, default is binary: +this only has any effect under Win32). +.Pp +.Fn BIO_set_fp +set the file pointer of a file BIO to +.Fa fp . +.Fa flags +has the same meaning as in +.Fn BIO_new_fp . +.Fn BIO_set_fp +is a macro. +.Pp +.Fn BIO_get_fp +retrieves the file pointer of a file BIO, it is a macro. +.Pp +.Xr BIO_seek 3 +is a macro that sets the position pointer to +.Fa offset +bytes from the start of file. +.Pp +.Xr BIO_tell 3 +returns the value of the position pointer. +.Pp +.Fn BIO_read_filename , +.Fn BIO_write_filename , +.Fn BIO_append_filename , +and +.Fn BIO_rw_filename +set the file BIO +.Fa b +to use file +.Fa name +for reading, writing, append or read write respectively. +.Sh NOTES +When wrapping stdout, stdin, or stderr, the underlying stream +should not normally be closed, so the +.Dv BIO_NOCLOSE +flag should be set. +.Pp +Because the file BIO calls the underlying stdio functions, any quirks +in stdio behaviour will be mirrored by the corresponding BIO. +.Pp +On Windows, +.Fn BIO_new_files +reserves for the filename argument to be UTF-8 encoded. +In other words, if you have to make it work in a multi-lingual +environment, encode file names in UTF-8. +.Sh RETURN VALUES +.Fn BIO_s_file +returns the file BIO method. +.Pp +.Fn BIO_new_file +and +.Fn BIO_new_fp +return a file BIO or +.Dv NULL +if an error occurred. +.Pp +.Fn BIO_set_fp +and +.Fn BIO_get_fp +return 1 for success or 0 for failure (although the current +implementation never returns 0). +.Pp +.Xr BIO_seek 3 +returns the same value as the underlying +.Xr fseek 3 +function: 0 for success or -1 for failure. +.Pp +.Xr BIO_tell 3 +returns the current file position. +.Pp +.Fn BIO_read_filename , +.Fn BIO_write_filename , +.Fn BIO_append_filename , +and +.Fn BIO_rw_filename +return 1 for success or 0 for failure. +.Sh EXAMPLES +File BIO "hello world": +.Bd -literal -offset indent +BIO *bio_out; +bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); +BIO_printf(bio_out, "Hello World\en"); +.Ed +.Pp +Alternative technique: +.Bd -literal -offset indent +BIO *bio_out; +bio_out = BIO_new(BIO_s_file()); +if(bio_out == NULL) /* Error ... */ +if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */ +BIO_printf(bio_out, "Hello World\en"); +.Ed +.Pp +Write to a file: +.Bd -literal -offset indent +BIO *out; +out = BIO_new_file("filename.txt", "w"); +if(!out) /* Error occurred */ +BIO_printf(out, "Hello World\en"); +BIO_free(out); +.Ed +.Pp +Alternative technique: +.Bd -literal -offset indent +BIO *out; +out = BIO_new(BIO_s_file()); +if(out == NULL) /* Error ... */ +if(!BIO_write_filename(out, "filename.txt")) /* Error ... */ +BIO_printf(out, "Hello World\en"); +BIO_free(out); +.Ed +.Sh SEE ALSO +.Xr BIO_read 3 , +.Xr BIO_seek 3 +.Sh BUGS +.Xr BIO_reset 3 +and +.Xr BIO_seek 3 +are implemented using +.Xr fseek 3 +on the underlying stream. +The return value for +.Xr fseek 3 +is 0 for success or -1 if an error occurred. +This differs from other types of BIO which will typically return +1 for success and a non positive value if an error occurred. diff --git a/lib/libcrypto/man/BIO_s_mem.3 b/lib/libcrypto/man/BIO_s_mem.3 new file mode 100644 index 00000000000..a37b4bff980 --- /dev/null +++ b/lib/libcrypto/man/BIO_s_mem.3 @@ -0,0 +1,190 @@ +.Dd $Mdocdate: February 16 2015 $ +.Dt BIO_S_MEM 3 +.Os +.Sh NAME +.Nm BIO_s_mem , +.Nm BIO_set_mem_eof_return , +.Nm BIO_get_mem_data , +.Nm BIO_set_mem_buf , +.Nm BIO_get_mem_ptr , +.Nm BIO_new_mem_buf +.Nd memory BIO +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO_METHOD * +.Fo BIO_s_mem +.Fa "void" +.Fc +.Ft long +.Fo BIO_set_mem_eof_return +.Fa "BIO *b" +.Fa "int v" +.Fc +.Ft long +.Fo BIO_get_mem_data +.Fa "BIO *b" +.Fa "char **pp" +.Fc +.Ft long +.Fo BIO_set_mem_buf +.Fa "BIO *b" +.Fa "BUF_MEM *bm" +.Fa "int c" +.Fc +.Ft long +.Fo BIO_get_mem_ptr +.Fa "BIO *b" +.Fa "BUF_MEM **pp" +.Fc +.Ft BIO * +.Fo BIO_new_mem_buf +.Fa "void *buf" +.Fa "int len" +.Fc +.Sh DESCRIPTION +.Fn BIO_s_mem +returns the memory BIO method function. +.Pp +A memory BIO is a source/sink BIO which uses memory for its I/O. +Data written to a memory BIO is stored in a +.Vt BUF_MEM +structure which is extended as appropriate to accommodate the stored data. +.Pp +Any data written to a memory BIO can be recalled by reading from it. +Unless the memory BIO is read only, +any data read from it is deleted from the BIO. +.Pp +Memory BIOs support +.Xr BIO_gets 3 +and +.Xr BIO_puts 3 . +.Pp +If the +.Dv BIO_CLOSE +flag is set when a memory BIO is freed, the underlying +.Dv BUF_MEM +structure is also freed. +.Pp +Calling +.Xr BIO_reset 3 +on a read/write memory BIO clears any data in it. +On a read only BIO it restores the BIO to its original state +and the read only data can be read again. +.Pp +.Xr BIO_eof 3 +is true if no data is in the BIO. +.Pp +.Xr BIO_ctrl_pending 3 +returns the number of bytes currently stored. +.Pp +.Xr BIO_set_mem_eof_return 3 +sets the behaviour of memory BIO +.Fa b +when it is empty. +If +.Fa v +is zero, then an empty memory BIO will return EOF: +It will return zero and +.Fn BIO_should_retry +will be false. +If +.Fa v +is non-zero then it will return +.Fa v +when it is empty and it will set the read retry flag: +.Fn BIO_read_retry +is true. +To avoid ambiguity with a normal positive return value +.Fa v +should be set to a negative value, typically -1. +.Pp +.Fn BIO_get_mem_data +sets +.Fa pp +to a pointer to the start of the memory BIO's data +and returns the total amount of data available. +It is implemented as a macro. +.Pp +.Fn BIO_set_mem_buf +sets the internal BUF_MEM structure to +.Fa bm +and sets the close flag to +.Fa c , +that is +.Fa c +should be either +.Dv BIO_CLOSE +or +.Dv BIO_NOCLOSE . +.Fn BIO_set_mem_buf +is a macro. +.Pp +.Fn BIO_get_mem_ptr +places the underlying +.Vt BUF_MEM +structure in +.Fa pp . +It is a macro. +.Pp +.Fn BIO_new_mem_buf +creates a memory BIO using +.Fa len +bytes of data at +.Fa buf . +If +.Fa len +is -1, then +.Fa buf +is assumed to be NUL terminated and its length is determined by +.Xr strlen 3 . +The BIO is set to a read only state and as a result cannot be written to. +This is useful when some data needs to be made available +from a static area of memory in the form of a BIO. +The supplied data is read directly from the supplied buffer: +it is +.Em not +copied first, so the supplied area of memory must be unchanged +until the BIO is freed. +.Sh NOTES +Writes to memory BIOs will always succeed if memory is available: +their size can grow indefinitely. +.Pp +Every read from a read/write memory BIO will remove the data just read +with an internal copy operation. +If a BIO contains a lot of data and it is read in small chunks, +the operation can be very slow. +The use of a read only memory BIO avoids this problem. +If the BIO must be read/write then adding a buffering BIO +to the chain will speed up the process. +.Sh EXAMPLES +Create a memory BIO and write some data to it: +.Bd -literal -offset indent +BIO *mem = BIO_new(BIO_s_mem()); +BIO_puts(mem, "Hello World\en"); +.Ed +.Pp +Create a read only memory BIO: +.Bd -literal -offset indent +char data[] = "Hello World"; +BIO *mem; +mem = BIO_new_mem_buf(data, -1); +.Ed +.Pp +Extract the +.Vt BUF_MEM +structure from a memory BIO and then free up the BIO: +.Bd -literal -offset indent +BUF_MEM *bptr; +BIO_get_mem_ptr(mem, &bptr); +/* Make sure BIO_free() leaves BUF_MEM alone. */ +BIO_set_close(mem, BIO_NOCLOSE); +BIO_free(mem); +.Ed +.Sh BUGS +There should be an option to set the maximum size of a memory BIO. +.Pp +There should be a way to "rewind" a read/write BIO without destroying +its contents. +.Pp +The copying operation should not occur after every small read +of a large BIO to improve efficiency. diff --git a/lib/libcrypto/man/BIO_s_null.3 b/lib/libcrypto/man/BIO_s_null.3 new file mode 100644 index 00000000000..05008aabfc9 --- /dev/null +++ b/lib/libcrypto/man/BIO_s_null.3 @@ -0,0 +1,32 @@ +.Dd $Mdocdate: February 16 2015 $ +.Dt BIO_S_NULL 3 +.Os +.Sh NAME +.Nm BIO_s_null +.Nd null data sink +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO_METHOD * +.Fo BIO_s_null +.Fa void +.Fc +.Sh DESCRIPTION +.Fn BIO_s_null +returns the null sink BIO method. +Data written to the null sink is discarded, reads return EOF. +.Sh NOTES +A null sink BIO behaves in a similar manner to the +.Xr null 4 +device. +.Pp +A null bio can be placed on the end of a chain to discard any data +passed through it. +.Pp +A null sink is useful if, for example, an application wishes +to digest some data by writing through a digest bio +but not send the digested data anywhere. +Since a BIO chain must normally include a source/sink BIO, +this can be achieved by adding a null sink BIO to the end of the chain. +.Sh RETURN VALUES +.Fn BIO_s_null +returns the null sink BIO method. diff --git a/lib/libcrypto/man/BIO_s_socket.3 b/lib/libcrypto/man/BIO_s_socket.3 new file mode 100644 index 00000000000..f7aff6a4c8f --- /dev/null +++ b/lib/libcrypto/man/BIO_s_socket.3 @@ -0,0 +1,99 @@ +.Dd $Mdocdate: February 16 2015 $ +.Dt BIO_S_SOCKET 3 +.Os +.Sh NAME +.Nm BIO_s_socket , +.Nm BIO_new_socket +.Nd socket BIO +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO_METHOD * +.Fo BIO_s_socket +.Fa void +.Fc +.Ft long +.Fo BIO_set_fd +.Fa "BIO *b" +.Fa "int fd" +.Fa "long close_flag" +.Fc +.Ft long +.Fo BIO_get_fd +.Fa "BIO *b" +.Fa "int *c" +.Fc +.Ft BIO * +.Fo BIO_new_socket +.Fa "int sock" +.Fa "int close_flag" +.Fc +.Sh DESCRIPTION +.Fn BIO_s_socket +returns the socket BIO method. +This is a wrapper around the platform's socket routines. +.Pp +.Xr BIO_read 3 +and +.Xr BIO_write 3 +read or write the underlying socket. +.Xr BIO_puts 3 +is supported but +.Xr BIO_gets 3 +is not. +.Pp +If the close flag is set, then the socket is shut down and closed +when the BIO is freed. +.Pp +.Fn BIO_set_fd +sets the socket of BIO +.Fa b +to +.Fa fd +and the close flag to +.Fa close_flag . +.Pp +.Fn BIO_get_fd +places the socket in +.Fa c +if it is not +.Dv NULL , +it also returns the socket. +If +.Fa c +is not +.Dv NULL +it should be of type +.Vt "int *" . +.Pp +.Fn BIO_new_socket +returns a socket BIO using +.Fa sock +and +.Fa close_flag . +.Sh NOTES +Socket BIOs also support any relevant functionality of file descriptor BIOs. +.Pp +The reason for having separate file descriptor and socket BIOs +is that on some platforms, sockets are not file descriptors +and use distinct I/O routines. +Windows is one such platform. +Any code mixing the two will not work on all platforms. +.Pp +.Fn BIO_set_fd +and +.Fn BIO_get_fd +are macros. +.Sh RETURN VALUES +.Fn BIO_s_socket +returns the socket BIO method. +.Pp +.Fn BIO_set_fd +always returns 1. +.Pp +.Fn BIO_get_fd +returns the socket or -1 if the BIO has not been initialized. +.Pp +.Fn BIO_new_socket +returns the newly allocated BIO or +.Dv NULL +if an error occurred. diff --git a/lib/libcrypto/man/BIO_set_callback.3 b/lib/libcrypto/man/BIO_set_callback.3 new file mode 100644 index 00000000000..39d284890ec --- /dev/null +++ b/lib/libcrypto/man/BIO_set_callback.3 @@ -0,0 +1,129 @@ +.Dd $Mdocdate: February 16 2015 $ +.Dt BIO_SET_CALLBACK 3 +.Os +.Sh NAME +.Nm BIO_set_callback , +.Nm BIO_get_callback , +.Nm BIO_set_callback_arg , +.Nm BIO_get_callback_arg , +.Nm BIO_debug_callback +.Nd BIO callback functions +.Sh SYNOPSIS +.In openssl/bio.h +.Fd #define BIO_set_callback(b,cb) ((b)->callback=(cb)) +.Fd #define BIO_get_callback(b) ((b)->callback) +.Fd #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg)) +.Fd #define BIO_get_callback_arg(b) ((b)->cb_arg) +.Ft long +.Fo BIO_debug_callback +.Fa "BIO *bio" +.Fa "int cmd" +.Fa "const char *argp" +.Fa "int argi" +.Fa "long argl" +.Fa "long ret" +.Fc +.Ft typedef long * +.Fo callback +.Fa "BIO *b" +.Fa "int oper" +.Fa "const char *argp" +.Fa "int argi" +.Fa "long argl" +.Fa "long retvalue" +.Fc +.Sh DESCRIPTION +.Fn BIO_set_callback +and +.Fn BIO_get_callback +set and retrieve the BIO callback, they are both macros. +The callback is called during most high level BIO operations. +It can be used for debugging purposes to trace operations on a BIO +or to modify its operation. +.Pp +.Fn BIO_set_callback_arg +and +.Fn BIO_get_callback_arg +are macros which can be used to set and retrieve an argument +for use in the callback. +.Pp +.Fn BIO_debug_callback +is a standard debugging callback which prints +out information relating to each BIO operation. +If the callback argument is set, it is interpreted as a BIO +to send the information to, otherwise stderr is used. +.Pp +.Fn callback +is the callback function itself. +The meaning of each argument is described below. +.Pp +The BIO the callback is attached to is passed in +.Fa b . +.Pp +.Fa oper +is set to the operation being performed. +For some operations the callback is called twice, +once before and once after the actual operation. +The latter case has +.Fa oper +or'ed with +.Dv BIO_CB_RETURN . +.Pp +The meaning of the arguments +.Fa argp , +.Fa argi +and +.Fa argl +depends on the value of +.Fa oper , +that is the operation being performed. +.Pp +.Fa retvalue +is the return value that would be returned to the application +if no callback were present. +The actual value returned is the return value of the callback itself. +In the case of callbacks called before the actual BIO operation, +1 is placed in retvalue. +If the return value is not positive, it will be immediately returned to +the application and the BIO operation will not be performed. +.Pp +The callback should normally simply return +.Fa retvalue +when it has finished processing, unless it specifically wishes +to modify the value returned to the application. +.Ss Callback operations +.Bl -tag -width Ds +.It Fn BIO_free b +.Fn callback b BIO_CB_FREE NULL 0L 0L 1L +is called before the free operation. +.It Fn BIO_read b out outl +.Fn callback b BIO_CB_READ out outl 0L 1L +is called before the read and +.Fn callback b BIO_CB_READ|BIO_CB_RETURN out outl 0L retvalue +after. +.It Fn BIO_write b in inl +.Fn callback b BIO_CB_WRITE in inl 0L 1L +is called before the write and +.Fn callback b BIO_CB_WRITE|BIO_CB_RETURN in inl 0L retvalue +after. +.It Fn BIO_gets b out outl +.Fn callback b BIO_CB_GETS out outl 0L 1L +is called before the operation and +.Fn callback b BIO_CB_GETS|BIO_CB_RETURN out outl 0L retvalue +after. +.It Fn BIO_puts b in +.Fn callback b BIO_CB_WRITE in 0 0L 1L +is called before the operation and +.Fn callback b BIO_CB_WRITE|BIO_CB_RETURN in 0 0L retvalue +after. +.It Fn BIO_ctrl b cmd larg parg +.Fn callback b BIO_CB_CTRL parg cmd larg 1L +is called before the call and +.Fn callback b BIO_CB_CTRL|BIO_CB_RETURN parg cmd larg ret +after. +.El +.Sh EXAMPLES +The +.Fn BIO_debug_callback +function is a good example, its source is in the file +.Pa crypto/bio/bio_cb.c . diff --git a/lib/libcrypto/man/BIO_should_retry.3 b/lib/libcrypto/man/BIO_should_retry.3 new file mode 100644 index 00000000000..cb5eda31215 --- /dev/null +++ b/lib/libcrypto/man/BIO_should_retry.3 @@ -0,0 +1,145 @@ +.Dd $Mdocdate: February 16 2015 $ +.Dt BIO_SHOULD_RETRY 3 +.Os +.Sh NAME +.Nm BIO_should_retry , +.Nm BIO_should_read , +.Nm BIO_should_write , +.Nm BIO_should_io_special , +.Nm BIO_retry_type , +.Nm BIO_get_retry_BIO , +.Nm BIO_get_retry_reason +.Nd BIO retry functions +.Sh SYNOPSIS +.In openssl/bio.h +.Pp +.Fd #define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ) +.Fd #define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE) +.Fd #define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL) +.Fd #define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS) +.Fd #define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY) +.Fd #define BIO_FLAGS_READ 0x01 +.Fd #define BIO_FLAGS_WRITE 0x02 +.Fd #define BIO_FLAGS_IO_SPECIAL 0x04 +.Fd #define BIO_FLAGS_RWS \e +.Fd \& (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL) +.Fd #define BIO_FLAGS_SHOULD_RETRY 0x08 +.Ft BIO * +.Fo BIO_get_retry_BIO +.Fa "BIO *bio" +.Fa "int *reason" +.Fc +.Ft int +.Fo BIO_get_retry_reason +.Fa "BIO *bio" +.Fc +.Sh DESCRIPTION +These functions determine why a BIO is not able to read or write data. +They will typically be called after a failed +.Xr BIO_read 3 +or +.Xr BIO_write 3 +call. +.Pp +.Fn BIO_should_retry +is true if the call that produced this condition +should be retried at a later time. +.Pp +If +.Fn BIO_should_retry +is false, the cause is an error condition. +.Pp +.Fn BIO_should_read +is true if the cause of the condition is that a BIO needs to read data. +.Pp +.Fn BIO_should_write +is true if the cause of the condition is that a BIO needs to write data. +.Pp +.Fn BIO_should_io_special +is true if some "special" condition, that is a reason other than +reading or writing, is the cause of the condition. +.Pp +.Fn BIO_retry_type +returns a mask of the cause of a retry condition consisting of the values +.Dv BIO_FLAGS_READ , +.Dv BIO_FLAGS_WRITE , +.Dv BIO_FLAGS_IO_SPECIAL +though current BIO types will only set one of these. +.Pp +.Fn BIO_get_retry_BIO +determines the precise reason for the special condition. +It returns the BIO that caused this condition and if +.Fa reason +is not +.Dv NULL +it contains the reason code. +The meaning of the reason code and the action that should be taken +depends on the type of BIO that resulted in this condition. +.Pp +.Fn BIO_get_retry_reason +returns the reason for a special condition +if passed the relevant BIO, for example as returned by +.Fn BIO_get_retry_BIO . +.Sh NOTES +If +.Fn BIO_should_retry +returns false, then the precise "error condition" depends on +the BIO type that caused it and the return code of the BIO operation. +For example if a call to +.Xr BIO_read 3 +on a socket BIO returns 0 and +.Fn BIO_should_retry +is false, then the cause will be that the connection closed. +A similar condition on a file BIO will mean that it has reached EOF. +Some BIO types may place additional information on the error queue. +For more details see the individual BIO type manual pages. +.Pp +If the underlying I/O structure is in a blocking mode, +almost all current BIO types will not request a retry, +because the underlying I/O calls will not. +If the application knows that the BIO type will never +signal a retry then it need not call +.Fn BIO_should_retry +after a failed BIO I/O call. +This is typically done with file BIOs. +.Pp +SSL BIOs are the only current exception to this rule: +they can request a retry even if the underlying I/O structure +is blocking, if a handshake occurs during a call to +.Xr BIO_read 3 . +An application can retry the failed call immediately +or avoid this situation by setting +.Dv SSL_MODE_AUTO_RETRY +on the underlying SSL structure. +.Pp +While an application may retry a failed non blocking call immediately, +this is likely to be very inefficient because the call will fail +repeatedly until data can be processed or is available. +An application will normally wait until the necessary condition +is satisfied. +How this is done depends on the underlying I/O structure. +.Pp +For example if the cause is ultimately a socket and +.Fn BIO_should_read +is true then a call to +.Xr select 2 +may be made to wait until data is available +and then retry the BIO operation. +By combining the retry conditions of several non blocking BIOs in a single +.Xr select 2 +call it is possible to service several BIOs in a single thread, +though the performance may be poor if SSL BIOs are present because +long delays can occur during the initial handshake process. +.Pp +It is possible for a BIO to block indefinitely if the underlying I/O +structure cannot process or return any data. +This depends on the behaviour of the platforms I/O functions. +This is often not desirable: one solution is to use non blocking I/O +and use a timeout on the +.Xr select 2 +(or equivalent) call. +.Sh BUGS +The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O: +they cannot retry after a partial read or write. +This is usually worked around by only passing the relevant data to ASN1 +functions when the entire structure can be read or written. diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index fcf94162483..2ac6e5b6f67 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.17 2015/02/14 14:09:01 schwarze Exp $ +# $OpenBSD: Makefile,v 1.18 2015/02/16 16:42:14 schwarze Exp $ .include <bsd.own.mk> # for NOMAN @@ -21,8 +21,6 @@ MAN= \ BIO_f_null.3 \ BIO_find_type.3 \ BIO_new.3 \ - -GENMAN= \ BIO_push.3 \ BIO_read.3 \ BIO_s_accept.3 \ @@ -35,6 +33,8 @@ GENMAN= \ BIO_s_socket.3 \ BIO_set_callback.3 \ BIO_should_retry.3 \ + +GENMAN= \ BN_BLINDING_new.3 \ BN_CTX_new.3 \ BN_CTX_start.3 \ diff --git a/lib/libssl/src/doc/crypto/BIO_push.pod b/lib/libssl/src/doc/crypto/BIO_push.pod deleted file mode 100644 index 39c964b2723..00000000000 --- a/lib/libssl/src/doc/crypto/BIO_push.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - -BIO_push, BIO_pop - add and remove BIOs from a chain. - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO * BIO_push(BIO *b,BIO *append); - BIO * BIO_pop(BIO *b); - -=head1 DESCRIPTION - -The BIO_push() function appends the BIO B<append> to B<b>, and returns -B<b>. - -BIO_pop() removes the BIO B<b> from a chain and returns the next BIO -in the chain, or NULL if there is no next BIO. The removed BIO then -becomes a single BIO with no association with the original chain, -it can thus be freed or attached to a different chain. - -=head1 NOTES - -The names of these functions are perhaps a little misleading. BIO_push() -joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain, -the deleted BIO does not need to be at the end of a chain. - -The process of calling BIO_push() and BIO_pop() on a BIO may have additional -consequences (a control call is made to the affected BIOs) any effects will -be noted in the descriptions of individual BIOs. - -=head1 EXAMPLES - -For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is -a base64 BIO and B<f> is a file BIO. - -If the call: - - BIO_push(b64, f); - -is made then the new chain will be B<b64-f>. After making the calls - - BIO_push(md2, b64); - BIO_push(md1, md2); - -the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested -by B<md1> and B<md2>, B<base64> encoded and written to B<f>. - -It should be noted that reading causes data to pass in the reverse -direction, that is data is read from B<f>, base64 B<decoded> and digested -by B<md1> and B<md2>. If the call: - - BIO_pop(md2); - -The call will return B<b64> and the new chain will be B<md1-b64-f>; data can -be written to B<md1> as before. - -=head1 RETURN VALUES - -BIO_push() returns the beginning of the chain, B<b>. - -BIO_pop() returns the next BIO in the chain, or NULL if there is no next -BIO. - -=cut diff --git a/lib/libssl/src/doc/crypto/BIO_read.pod b/lib/libssl/src/doc/crypto/BIO_read.pod deleted file mode 100644 index e527bff8d02..00000000000 --- a/lib/libssl/src/doc/crypto/BIO_read.pod +++ /dev/null @@ -1,66 +0,0 @@ -=pod - -=head1 NAME - -BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - int BIO_read(BIO *b, void *buf, int len); - int BIO_gets(BIO *b, char *buf, int size); - int BIO_write(BIO *b, const void *buf, int len); - int BIO_puts(BIO *b, const char *buf); - -=head1 DESCRIPTION - -BIO_read() attempts to read B<len> bytes from BIO B<b> and places -the data in B<buf>. - -BIO_gets() performs the BIOs "gets" operation and places the data -in B<buf>. Usually this operation will attempt to read a line of data -from the BIO of maximum length B<len>. There are exceptions to this -however, for example BIO_gets() on a digest BIO will calculate and -return the digest and other BIOs may not support BIO_gets() at all. - -BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>. - -BIO_puts() attempts to write a null terminated string B<buf> to BIO B<b>. - -=head1 RETURN VALUES - -All these functions return either the amount of data successfully read or -written (if the return value is positive) or that no data was successfully -read or written if the result is 0 or -1. If the return value is -2 then -the operation is not implemented in the specific BIO type. - -=head1 NOTES - -A 0 or -1 return is not necessarily an indication of an error. In -particular when the source/sink is non-blocking or of a certain type -it may merely be an indication that no data is currently available and that -the application should retry the operation later. - -One technique sometimes used with blocking sockets is to use a system call -(such as select(), poll() or equivalent) to determine when data is available -and then call read() to read the data. The equivalent with BIOs (that is call -select() on the underlying I/O structure and then call BIO_read() to -read the data) should B<not> be used because a single call to BIO_read() -can cause several reads (and writes in the case of SSL BIOs) on the underlying -I/O structure and may block as a result. Instead select() (or equivalent) -should be combined with non blocking I/O so successive reads will request -a retry instead of blocking. - -See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to -determine the cause of a retry and other I/O issues. - -If the BIO_gets() function is not supported by a BIO then it possible to -work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)> -to the chain. - -=head1 SEE ALSO - -L<BIO_should_retry(3)|BIO_should_retry(3)> - -=cut diff --git a/lib/libssl/src/doc/crypto/BIO_s_accept.pod b/lib/libssl/src/doc/crypto/BIO_s_accept.pod deleted file mode 100644 index 5729d381934..00000000000 --- a/lib/libssl/src/doc/crypto/BIO_s_accept.pod +++ /dev/null @@ -1,189 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, BIO_new_accept, -BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode, -BIO_get_bind_mode, BIO_do_accept - accept BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD *BIO_s_accept(void); - - long BIO_set_accept_port(BIO *b, char *name); - char *BIO_get_accept_port(BIO *b); - - BIO *BIO_new_accept(char *host_port); - - long BIO_set_nbio_accept(BIO *b, int n); - long BIO_set_accept_bios(BIO *b, char *bio); - - long BIO_set_bind_mode(BIO *b, long mode); - long BIO_get_bind_mode(BIO *b, long dummy); - - #define BIO_BIND_NORMAL 0 - #define BIO_BIND_REUSEADDR_IF_UNUSED 1 - #define BIO_BIND_REUSEADDR 2 - - int BIO_do_accept(BIO *b); - -=head1 DESCRIPTION - -BIO_s_accept() returns the accept BIO method. This is a wrapper -round the platform's TCP/IP socket accept routines. - -Using accept BIOs, TCP/IP connections can be accepted and data -transferred using only BIO routines. In this way any platform -specific operations are hidden by the BIO abstraction. - -Read and write operations on an accept BIO will perform I/O -on the underlying connection. If no connection is established -and the port (see below) is set up properly then the BIO -waits for an incoming connection. - -Accept BIOs support BIO_puts() but not BIO_gets(). - -If the close flag is set on an accept BIO then any active -connection on that chain is shutdown and the socket closed when -the BIO is freed. - -Calling BIO_reset() on a accept BIO will close any active -connection and reset the BIO into a state where it awaits another -incoming connection. - -BIO_get_fd() and BIO_set_fd() can be called to retrieve or set -the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)> - -BIO_set_accept_port() uses the string B<name> to set the accept -port. The port is represented as a string of the form "host:port", -where "host" is the interface to use and "port" is the port. -Either or both values can be "*" which is interpreted as meaning -any interface or port respectively. "port" has the same syntax -as the port specified in BIO_set_conn_port() for connect BIOs, -that is it can be a numerical port string or a string to lookup -using getservbyname() and a string table. - -BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into -a single call: that is it creates a new accept BIO with port -B<host_port>. - -BIO_set_nbio_accept() sets the accept socket to blocking mode -(the default) if B<n> is 0 or non blocking mode if B<n> is 1. - -BIO_set_accept_bios() can be used to set a chain of BIOs which -will be duplicated and prepended to the chain when an incoming -connection is received. This is useful if, for example, a -buffering or SSL BIO is required for each connection. The -chain of BIOs must not be freed after this call, they will -be automatically freed when the accept BIO is freed. - -BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve -the current bind mode. If BIO_BIND_NORMAL (the default) is set -then another socket cannot be bound to the same port. If -BIO_BIND_REUSEADDR is set then other sockets can bind to the -same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and -attempt is first made to use BIO_BIN_NORMAL, if this fails -and the port is not in use then a second attempt is made -using BIO_BIND_REUSEADDR. - -BIO_do_accept() serves two functions. When it is first -called, after the accept BIO has been setup, it will attempt -to create the accept socket and bind an address to it. Second -and subsequent calls to BIO_do_accept() will await an incoming -connection, or request a retry in non blocking mode. - -=head1 NOTES - -When an accept BIO is at the end of a chain it will await an -incoming connection before processing I/O calls. When an accept -BIO is not at then end of a chain it passes I/O calls to the next -BIO in the chain. - -When a connection is established a new socket BIO is created for -the connection and appended to the chain. That is the chain is now -accept->socket. This effectively means that attempting I/O on -an initial accept socket will await an incoming connection then -perform I/O on it. - -If any additional BIOs have been set using BIO_set_accept_bios() -then they are placed between the socket and the accept BIO, -that is the chain will be accept->otherbios->socket. - -If a server wishes to process multiple connections (as is normally -the case) then the accept BIO must be made available for further -incoming connections. This can be done by waiting for a connection and -then calling: - - connection = BIO_pop(accept); - -After this call B<connection> will contain a BIO for the recently -established connection and B<accept> will now be a single BIO -again which can be used to await further incoming connections. -If no further connections will be accepted the B<accept> can -be freed using BIO_free(). - -If only a single connection will be processed it is possible to -perform I/O using the accept BIO itself. This is often undesirable -however because the accept BIO will still accept additional incoming -connections. This can be resolved by using BIO_pop() (see above) -and freeing up the accept BIO after the initial connection. - -If the underlying accept socket is non-blocking and BIO_do_accept() is -called to await an incoming connection it is possible for -BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens -then it is an indication that an accept attempt would block: the application -should take appropriate action to wait until the underlying socket has -accepted a connection and retry the call. - -BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(), -BIO_set_accept_bios(), BIO_set_bind_mode(), BIO_get_bind_mode() and -BIO_do_accept() are macros. - -=head1 EXAMPLE - -This example accepts two connections on port 4444, sends messages -down each and finally closes both down. - - BIO *abio, *cbio, *cbio2; - ERR_load_crypto_strings(); - abio = BIO_new_accept("4444"); - - /* First call to BIO_accept() sets up accept BIO */ - if (BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error setting up accept\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - - /* Wait for incoming connection */ - if (BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error accepting connection\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - fprintf(stderr, "Connection 1 established\n"); - /* Retrieve BIO for connection */ - cbio = BIO_pop(abio); - BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n"); - fprintf(stderr, "Sent out data on connection 1\n"); - /* Wait for another connection */ - if (BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error accepting connection\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - fprintf(stderr, "Connection 2 established\n"); - /* Close accept BIO to refuse further connections */ - cbio2 = BIO_pop(abio); - BIO_free(abio); - BIO_puts(cbio2, "Connection 2: Sending out Data on second\n"); - fprintf(stderr, "Sent out data on connection 2\n"); - - BIO_puts(cbio, "Connection 1: Second connection established\n"); - /* Close the two established connections */ - BIO_free(cbio); - BIO_free(cbio2); - -=cut diff --git a/lib/libssl/src/doc/crypto/BIO_s_bio.pod b/lib/libssl/src/doc/crypto/BIO_s_bio.pod deleted file mode 100644 index 61ded32a024..00000000000 --- a/lib/libssl/src/doc/crypto/BIO_s_bio.pod +++ /dev/null @@ -1,185 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, -BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, -BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, -BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD *BIO_s_bio(void); - - #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2) - #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL) - - #define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL) - - #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL) - #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL) - - int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); - - #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL) - size_t BIO_ctrl_get_write_guarantee(BIO *b); - - #define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL) - size_t BIO_ctrl_get_read_request(BIO *b); - - int BIO_ctrl_reset_read_request(BIO *b); - -=head1 DESCRIPTION - -BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of -source/sink BIOs where data written to either half of the pair is buffered and -can be read from the other half. Both halves must usually by handled by the -same application thread since no locking is done on the internal data -structures. - -Since BIO chains typically end in a source/sink BIO it is possible to make this -one half of a BIO pair and have all the data processed by the chain under -application control. - -One typical use of BIO pairs is to place TLS/SSL I/O under application control, -this can be used when the application wishes to use a non standard transport -for TLS/SSL or the normal socket routines are inappropriate. - -Calls to BIO_read() will read data from the buffer or request a retry if no -data is available. - -Calls to BIO_write() will place data in the buffer or request a retry if the -buffer is full. - -The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to -determine the amount of pending data in the read or write buffer. - -BIO_reset() clears any data in the write buffer. - -BIO_make_bio_pair() joins two separate BIOs into a connected pair. - -BIO_destroy_pair() destroys the association between two connected BIOs. Freeing -up any half of the pair will automatically destroy the association. - -BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further -writes on BIO B<b> are allowed (they will return an error). Reads on the other -half of the pair will return any pending data or EOF when all pending data has -been read. - -BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>. -If the size is not initialized a default value is used. This is currently -17K, sufficient for a maximum size TLS record. - -BIO_get_write_buf_size() returns the size of the write buffer. - -BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and -BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2> -with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is -zero then the default size is used. BIO_new_bio_pair() does not check whether -B<bio1> or B<bio2> do point to some other BIO, the values are overwritten, -BIO_free() is not called. - -BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum -length of data that can be currently written to the BIO. Writes larger than -this value will return a value from BIO_write() less than the amount requested -or if the buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a -function whereas BIO_get_write_guarantee() is a macro. - -BIO_get_read_request() and BIO_ctrl_get_read_request() return the -amount of data requested, or the buffer size if it is less, if the -last read attempt at the other half of the BIO pair failed due to an -empty buffer. This can be used to determine how much data should be -written to the BIO so the next read will succeed: this is most useful -in TLS/SSL applications where the amount of data read is usually -meaningful rather than just a buffer size. After a successful read -this call will return zero. It also will return zero once new data -has been written satisfying the read request or part of it. -Note that BIO_get_read_request() never returns an amount larger -than that returned by BIO_get_write_guarantee(). - -BIO_ctrl_reset_read_request() can also be used to reset the value returned by -BIO_get_read_request() to zero. - -=head1 NOTES - -Both halves of a BIO pair should be freed. That is even if one half is implicit -freed due to a BIO_free_all() or SSL_free() call the other half needs to be -freed. - -When used in bidirectional applications (such as TLS/SSL) care should be taken -to flush any data in the write buffer. This can be done by calling -BIO_pending() on the other half of the pair and, if any data is pending, -reading it and sending it to the underlying transport. This must be done before -any normal processing (such as calling select() ) due to a request and -BIO_should_read() being true. - -To see why this is important consider a case where a request is sent using -BIO_write() and a response read with BIO_read(), this can occur during an -TLS/SSL handshake for example. BIO_write() will succeed and place data in the -write buffer. BIO_read() will initially fail and BIO_should_read() will be -true. If the application then waits for data to be available on the underlying -transport before flushing the write buffer it will never succeed because the -request was never sent! - -=head1 RETURN VALUES - -BIO_new_bio_pair() returns 1 on success, with the new BIOs available in -B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the -locations for B<bio1> and B<bio2>. Check the error stack for more information. - -[TODO: More return values need to be added here] - -=head1 EXAMPLE - -The BIO pair can be used to have full control over the network access of an -application. The application can call select() on the socket as required -without having to go through the SSL-interface. - - BIO *internal_bio, *network_bio; - ... - BIO_new_bio_pair(internal_bio, 0, network_bio, 0); - SSL_set_bio(ssl, internal_bio, internal_bio); - SSL_operations(); - ... - - application | TLS-engine - | | - +----------> SSL_operations() - | /\ || - | || \/ - | BIO-pair (internal_bio) - +----------< BIO-pair (network_bio) - | | - socket | - - ... - SSL_free(ssl); /* implicitly frees internal_bio */ - BIO_free(network_bio); - ... - -As the BIO pair will only buffer the data and never directly access the -connection, it behaves non-blocking and will return as soon as the write -buffer is full or the read buffer is drained. Then the application has to -flush the write buffer and/or fill the read buffer. - -Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO -and must be transfered to the network. Use BIO_ctrl_get_read_request() to -find out, how many bytes must be written into the buffer before the -SSL_operation() can successfully be continued. - -=head1 WARNING - -As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ -condition, but there is still data in the write buffer. An application must -not rely on the error value of SSL_operation() but must assure that the -write buffer is always flushed first. Otherwise a deadlock may occur as -the peer might be waiting for the data before being able to continue. - -=head1 SEE ALSO - -L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, -L<BIO_should_retry(3)|BIO_should_retry(3)>, L<BIO_read(3)|BIO_read(3)> - -=cut diff --git a/lib/libssl/src/doc/crypto/BIO_s_connect.pod b/lib/libssl/src/doc/crypto/BIO_s_connect.pod deleted file mode 100644 index 45832e52f39..00000000000 --- a/lib/libssl/src/doc/crypto/BIO_s_connect.pod +++ /dev/null @@ -1,191 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port, -BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname, -BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port, -BIO_set_nbio, BIO_do_connect - connect BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_s_connect(void); - - BIO *BIO_new_connect(char *name); - - long BIO_set_conn_hostname(BIO *b, char *name); - long BIO_set_conn_port(BIO *b, char *port); - long BIO_set_conn_ip(BIO *b, char *ip); - long BIO_set_conn_int_port(BIO *b, char *port); - char *BIO_get_conn_hostname(BIO *b); - char *BIO_get_conn_port(BIO *b); - char *BIO_get_conn_ip(BIO *b, dummy); - long BIO_get_conn_int_port(BIO *b, int port); - - long BIO_set_nbio(BIO *b, long n); - - int BIO_do_connect(BIO *b); - -=head1 DESCRIPTION - -BIO_s_connect() returns the connect BIO method. This is a wrapper -round the platform's TCP/IP socket connection routines. - -Using connect BIOs, TCP/IP connections can be made and data -transferred using only BIO routines. In this way any platform -specific operations are hidden by the BIO abstraction. - -Read and write operations on a connect BIO will perform I/O -on the underlying connection. If no connection is established -and the port and hostname (see below) is set up properly then -a connection is established first. - -Connect BIOs support BIO_puts() but not BIO_gets(). - -If the close flag is set on a connect BIO then any active -connection is shutdown and the socket closed when the BIO -is freed. - -Calling BIO_reset() on a connect BIO will close any active -connection and reset the BIO into a state where it can connect -to the same host again. - -BIO_get_fd() places the underlying socket in B<c> if it is not NULL, -it also returns the socket . If B<c> is not NULL it should be of -type (int *). - -BIO_set_conn_hostname() uses the string B<name> to set the hostname. -The hostname can be an IP address. The hostname can also include the -port in the form hostname:port . It is also acceptable to use the -form "hostname/any/other/path" or "hostname:port/any/other/path". - -BIO_set_conn_port() sets the port to B<port>. B<port> can be the -numerical form or a string such as "http". A string will be looked -up first using getservbyname() on the host platform but if that -fails a standard table of port names will be used. Currently the -list is http, telnet, socks, https, ssl, ftp, gopher and wais. - -BIO_set_conn_ip() sets the IP address to B<ip> using binary form, -that is four bytes specifying the IP address in big-endian form. - -BIO_set_conn_int_port() sets the port using B<port>. B<port> should -be of type (int *). - -BIO_get_conn_hostname() returns the hostname of the connect BIO or -NULL if the BIO is initialized but no hostname is set. -This return value is an internal pointer which should not be modified. - -BIO_get_conn_port() returns the port as a string. - -BIO_get_conn_ip() returns the IP address in binary form. - -BIO_get_conn_int_port() returns the port as an int. - -BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is -zero then blocking I/O is set. If B<n> is 1 then non blocking I/O -is set. Blocking I/O is the default. The call to BIO_set_nbio() -should be made before the connection is established because -non blocking I/O is set during the connect process. - -BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into -a single call: that is it creates a new connect BIO with B<name>. - -BIO_do_connect() attempts to connect the supplied BIO. It returns 1 -if the connection was established successfully. A zero or negative -value is returned if the connection could not be established, the -call BIO_should_retry() should be used for non blocking connect BIOs -to determine if the call should be retried. - -=head1 NOTES - -If blocking I/O is set then a non positive return value from any -I/O call is caused by an error condition, although a zero return -will normally mean that the connection was closed. - -If the port name is supplied as part of the host name then this will -override any value set with BIO_set_conn_port(). This may be undesirable -if the application does not wish to allow connection to arbitrary -ports. This can be avoided by checking for the presence of the ':' -character in the passed hostname and either indicating an error or -truncating the string at that point. - -The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(), -BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a -connection attempt is made. Before any connection attempt the values -returned are those set by the application itself. - -Applications do not have to call BIO_do_connect() but may wish to do -so to separate the connection process from other I/O processing. - -If non blocking I/O is set then retries will be requested as appropriate. - -It addition to BIO_should_read() and BIO_should_write() it is also -possible for BIO_should_io_special() to be true during the initial -connection process with the reason BIO_RR_CONNECT. If this is returned -then this is an indication that a connection attempt would block, -the application should then take appropriate action to wait until -the underlying socket has connected and retry the call. - -BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(), -BIO_set_conn_int_port(), BIO_get_conn_hostname(), BIO_get_conn_port(), -BIO_get_conn_ip(), BIO_get_conn_int_port(), BIO_set_nbio() and -BIO_do_connect() are macros. - -=head1 RETURN VALUES - -BIO_s_connect() returns the connect BIO method. - -BIO_get_fd() returns the socket or -1 if the BIO has not -been initialized. - -BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and -BIO_set_conn_int_port() always return 1. - -BIO_get_conn_hostname() returns the connected hostname or NULL is -none was set. - -BIO_get_conn_port() returns a string representing the connected -port or NULL if not set. - -BIO_get_conn_ip() returns a pointer to the connected IP address in -binary form or all zeros if not set. - -BIO_get_conn_int_port() returns the connected port or 0 if none was -set. - -BIO_set_nbio() always returns 1. - -BIO_do_connect() returns 1 if the connection was successfully -established and 0 or -1 if the connection failed. - -=head1 EXAMPLE - -This is example connects to a webserver on the local host and attempts -to retrieve a page and copy the result to standard output. - - - BIO *cbio, *out; - int len; - char tmpbuf[1024]; - - ERR_load_crypto_strings(); - cbio = BIO_new_connect("localhost:http"); - out = BIO_new_fp(stdout, BIO_NOCLOSE); - if (BIO_do_connect(cbio) <= 0) { - fprintf(stderr, "Error connecting to server\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } - BIO_puts(cbio, "GET / HTTP/1.0\n\n"); - for(;;) { - len = BIO_read(cbio, tmpbuf, 1024); - if (len <= 0) - break; - BIO_write(out, tmpbuf, len); - } - BIO_free(cbio); - BIO_free(out); - -=cut diff --git a/lib/libssl/src/doc/crypto/BIO_s_fd.pod b/lib/libssl/src/doc/crypto/BIO_s_fd.pod deleted file mode 100644 index 22b7575ba03..00000000000 --- a/lib/libssl/src/doc/crypto/BIO_s_fd.pod +++ /dev/null @@ -1,91 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_s_fd(void); - - #define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd) - #define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c) - - BIO *BIO_new_fd(int fd, int close_flag); - -=head1 DESCRIPTION - -BIO_s_fd() returns the file descriptor BIO method. This is a wrapper -round the platforms file descriptor routines such as read() and write(). - -BIO_read() and BIO_write() read or write the underlying descriptor. -BIO_puts() is supported but BIO_gets() is not. - -If the close flag is set then then close() is called on the underlying -file descriptor when the BIO is freed. - -BIO_reset() attempts to change the file pointer to the start of file -using lseek(fd, 0, 0). - -BIO_seek() sets the file pointer to position B<ofs> from start of file -using lseek(fd, ofs, 0). - -BIO_tell() returns the current file position by calling lseek(fd, 0, 1). - -BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close -flag to B<c>. - -BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also -returns the file descriptor. If B<c> is not NULL it should be of type -(int *). - -BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>. - -=head1 NOTES - -The behaviour of BIO_read() and BIO_write() depends on the behavior of the -platforms read() and write() calls on the descriptor. If the underlying file -descriptor is in a non blocking mode then the BIO will behave in the manner -described in the L<BIO_read(3)|BIO_read(3)> and -L<BIO_should_retry(3)|BIO_should_retry(3)> manual pages. - -File descriptor BIOs should not be used for socket I/O. Use socket BIOs -instead. - -=head1 RETURN VALUES - -BIO_s_fd() returns the file descriptor BIO method. - -BIO_reset() returns zero for success and -1 if an error occurred. -BIO_seek() and BIO_tell() return the current file position or -1 -is an error occurred. These values reflect the underlying lseek() -behaviour. - -BIO_set_fd() always returns 1. - -BIO_get_fd() returns the file descriptor or -1 if the BIO has not -been initialized. - -BIO_new_fd() returns the newly allocated BIO or NULL is an error -occurred. - -=head1 EXAMPLE - -This is a file descriptor BIO version of "Hello World": - - BIO *out; - out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE); - BIO_printf(out, "Hello World\n"); - BIO_free(out); - -=head1 SEE ALSO - -L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, -L<BIO_reset(3)|BIO_reset(3)>, L<BIO_read(3)|BIO_read(3)>, -L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>, -L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>, -L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)> - -=cut diff --git a/lib/libssl/src/doc/crypto/BIO_s_file.pod b/lib/libssl/src/doc/crypto/BIO_s_file.pod deleted file mode 100644 index 0c9cb824da8..00000000000 --- a/lib/libssl/src/doc/crypto/BIO_s_file.pod +++ /dev/null @@ -1,150 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp, -BIO_read_filename, BIO_write_filename, BIO_append_filename, -BIO_rw_filename - FILE bio - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_s_file(void); - BIO *BIO_new_file(const char *filename, const char *mode); - BIO *BIO_new_fp(FILE *stream, int flags); - - BIO_set_fp(BIO *b,FILE *fp, int flags); - BIO_get_fp(BIO *b,FILE **fpp); - - int BIO_read_filename(BIO *b, char *name) - int BIO_write_filename(BIO *b, char *name) - int BIO_append_filename(BIO *b, char *name) - int BIO_rw_filename(BIO *b, char *name) - -=head1 DESCRIPTION - -BIO_s_file() returns the BIO file method. As its name implies it -is a wrapper round the stdio FILE structure and it is a -source/sink BIO. - -Calls to BIO_read() and BIO_write() read and write data to the -underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs. - -BIO_flush() on a file BIO calls the fflush() function on the wrapped -stream. - -BIO_reset() attempts to change the file pointer to the start of file -using fseek(stream, 0, 0). - -BIO_seek() sets the file pointer to position B<ofs> from start of file -using fseek(stream, ofs, 0). - -BIO_eof() calls feof(). - -Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO -is freed. - -BIO_new_file() creates a new file BIO with mode B<mode> the meaning -of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE -flag is set on the returned BIO. - -BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be: -BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying -stream to text mode, default is binary: this only has any effect under -Win32). - -BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same -meaning as in BIO_new_fp(), it is a macro. - -BIO_get_fp() retrieves the fp of a file BIO, it is a macro. - -BIO_seek() is a macro that sets the position pointer to B<offset> bytes -from the start of file. - -BIO_tell() returns the value of the position pointer. - -BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and -BIO_rw_filename() set the file BIO B<b> to use file B<name> for -reading, writing, append or read write respectively. - -=head1 NOTES - -When wrapping stdout, stdin or stderr the underlying stream should not -normally be closed so the BIO_NOCLOSE flag should be set. - -Because the file BIO calls the underlying stdio functions any quirks -in stdio behaviour will be mirrored by the corresponding BIO. - -On Windows BIO_new_files reserves for the filename argument to be -UTF-8 encoded. In other words if you have to make it work in multi- -lingual environment, encode file names in UTF-8. - -=head1 EXAMPLES - -File BIO "hello world": - - BIO *bio_out; - bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); - BIO_printf(bio_out, "Hello World\n"); - -Alternative technique: - - BIO *bio_out; - bio_out = BIO_new(BIO_s_file()); - if(bio_out == NULL) /* Error ... */ - if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */ - BIO_printf(bio_out, "Hello World\n"); - -Write to a file: - - BIO *out; - out = BIO_new_file("filename.txt", "w"); - if(!out) /* Error occurred */ - BIO_printf(out, "Hello World\n"); - BIO_free(out); - -Alternative technique: - - BIO *out; - out = BIO_new(BIO_s_file()); - if(out == NULL) /* Error ... */ - if(!BIO_write_filename(out, "filename.txt")) /* Error ... */ - BIO_printf(out, "Hello World\n"); - BIO_free(out); - -=head1 RETURN VALUES - -BIO_s_file() returns the file BIO method. - -BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error -occurred. - -BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure -(although the current implementation never return 0). - -BIO_seek() returns the same value as the underlying fseek() function: -0 for success or -1 for failure. - -BIO_tell() returns the current file position. - -BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and -BIO_rw_filename() return 1 for success or 0 for failure. - -=head1 BUGS - -BIO_reset() and BIO_seek() are implemented using fseek() on the underlying -stream. The return value for fseek() is 0 for success or -1 if an error -occurred this differs from other types of BIO which will typically return -1 for success and a non positive value if an error occurred. - -=head1 SEE ALSO - -L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, -L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>, -L<BIO_read(3)|BIO_read(3)>, -L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>, -L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>, -L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)> - -=cut diff --git a/lib/libssl/src/doc/crypto/BIO_s_mem.pod b/lib/libssl/src/doc/crypto/BIO_s_mem.pod deleted file mode 100644 index 4541b3fc556..00000000000 --- a/lib/libssl/src/doc/crypto/BIO_s_mem.pod +++ /dev/null @@ -1,112 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, -BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_s_mem(void); - - BIO_set_mem_eof_return(BIO *b,int v) - long BIO_get_mem_data(BIO *b, char **pp) - BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c) - BIO_get_mem_ptr(BIO *b,BUF_MEM **pp) - - BIO *BIO_new_mem_buf(void *buf, int len); - -=head1 DESCRIPTION - -BIO_s_mem() return the memory BIO method function. - -A memory BIO is a source/sink BIO which uses memory for its I/O. Data -written to a memory BIO is stored in a BUF_MEM structure which is extended -as appropriate to accommodate the stored data. - -Any data written to a memory BIO can be recalled by reading from it. -Unless the memory BIO is read only any data read from it is deleted from -the BIO. - -Memory BIOs support BIO_gets() and BIO_puts(). - -If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying -BUF_MEM structure is also freed. - -Calling BIO_reset() on a read write memory BIO clears any data in it. On a -read only BIO it restores the BIO to its original state and the read only -data can be read again. - -BIO_eof() is true if no data is in the BIO. - -BIO_ctrl_pending() returns the number of bytes currently stored. - -BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is -empty. If the B<v> is zero then an empty memory BIO will return EOF (that is -it will return zero and BIO_should_retry(b) will be false. If B<v> is non -zero then it will return B<v> when it is empty and it will set the read retry -flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal -positive return value B<v> should be set to a negative value, typically -1. - -BIO_get_mem_data() sets B<pp> to a pointer to the start of the memory BIOs data -and returns the total amount of data available. It is implemented as a macro. - -BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the -close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE. -It is a macro. - -BIO_get_mem_ptr() places the underlying BUF_MEM structure in B<pp>. It is -a macro. - -BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>, -if B<len> is -1 then the B<buf> is assumed to be null terminated and its -length is determined by B<strlen>. The BIO is set to a read only state and -as a result cannot be written to. This is useful when some data needs to be -made available from a static area of memory in the form of a BIO. The -supplied data is read directly from the supplied buffer: it is B<not> copied -first, so the supplied area of memory must be unchanged until the BIO is freed. - -=head1 NOTES - -Writes to memory BIOs will always succeed if memory is available: that is -their size can grow indefinitely. - -Every read from a read write memory BIO will remove the data just read with -an internal copy operation, if a BIO contains a lot of data and it is -read in small chunks the operation can be very slow. The use of a read only -memory BIO avoids this problem. If the BIO must be read write then adding -a buffering BIO to the chain will speed up the process. - -=head1 BUGS - -There should be an option to set the maximum size of a memory BIO. - -There should be a way to "rewind" a read write BIO without destroying -its contents. - -The copying operation should not occur after every small read of a large BIO -to improve efficiency. - -=head1 EXAMPLE - -Create a memory BIO and write some data to it: - - BIO *mem = BIO_new(BIO_s_mem()); - BIO_puts(mem, "Hello World\n"); - -Create a read only memory BIO: - - char data[] = "Hello World"; - BIO *mem; - mem = BIO_new_mem_buf(data, -1); - -Extract the BUF_MEM structure from a memory BIO and then free up the BIO: - - BUF_MEM *bptr; - BIO_get_mem_ptr(mem, &bptr); - BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */ - BIO_free(mem); - -=cut diff --git a/lib/libssl/src/doc/crypto/BIO_s_null.pod b/lib/libssl/src/doc/crypto/BIO_s_null.pod deleted file mode 100644 index 9f7d4ac46a2..00000000000 --- a/lib/libssl/src/doc/crypto/BIO_s_null.pod +++ /dev/null @@ -1,35 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_null - null data sink - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_s_null(void); - -=head1 DESCRIPTION - -BIO_s_null() returns the null sink BIO method. Data written to -the null sink is discarded, reads return EOF. - -=head1 NOTES - -A null sink BIO behaves in a similar manner to the Unix /dev/null -device. - -A null bio can be placed on the end of a chain to discard any data -passed through it. - -A null sink is useful if, for example, an application wishes to digest some -data by writing through a digest bio but not send the digested data anywhere. -Since a BIO chain must normally include a source/sink BIO this can be achieved -by adding a null sink BIO to the end of the chain - -=head1 RETURN VALUES - -BIO_s_null() returns the null sink BIO method. - -=cut diff --git a/lib/libssl/src/doc/crypto/BIO_s_socket.pod b/lib/libssl/src/doc/crypto/BIO_s_socket.pod deleted file mode 100644 index 402aff26e20..00000000000 --- a/lib/libssl/src/doc/crypto/BIO_s_socket.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_socket, BIO_new_socket - socket BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD *BIO_s_socket(void); - - long BIO_set_fd(BIO *b, int fd, long close_flag); - long BIO_get_fd(BIO *b, int *c); - - BIO *BIO_new_socket(int sock, int close_flag); - -=head1 DESCRIPTION - -BIO_s_socket() returns the socket BIO method. This is a wrapper -round the platform's socket routines. - -BIO_read() and BIO_write() read or write the underlying socket. -BIO_puts() is supported but BIO_gets() is not. - -If the close flag is set then the socket is shut down and closed -when the BIO is freed. - -BIO_set_fd() sets the socket of BIO B<b> to B<fd> and the close -flag to B<close_flag>. - -BIO_get_fd() places the socket in B<c> if it is not NULL, it also -returns the socket. If B<c> is not NULL it should be of type (int *). - -BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>. - -=head1 NOTES - -Socket BIOs also support any relevant functionality of file descriptor -BIOs. - -The reason for having separate file descriptor and socket BIOs is that on some -platforms sockets are not file descriptors and use distinct I/O routines, -Windows is one such platform. Any code mixing the two will not work on -all platforms. - -BIO_set_fd() and BIO_get_fd() are macros. - -=head1 RETURN VALUES - -BIO_s_socket() returns the socket BIO method. - -BIO_set_fd() always returns 1. - -BIO_get_fd() returns the socket or -1 if the BIO has not been -initialized. - -BIO_new_socket() returns the newly allocated BIO or NULL is an error -occurred. - -=cut diff --git a/lib/libssl/src/doc/crypto/BIO_set_callback.pod b/lib/libssl/src/doc/crypto/BIO_set_callback.pod deleted file mode 100644 index 8e4e5900d9c..00000000000 --- a/lib/libssl/src/doc/crypto/BIO_set_callback.pod +++ /dev/null @@ -1,105 +0,0 @@ -=pod - -=head1 NAME - -BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, -BIO_debug_callback - BIO callback functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - #define BIO_set_callback(b,cb) ((b)->callback=(cb)) - #define BIO_get_callback(b) ((b)->callback) - #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg)) - #define BIO_get_callback_arg(b) ((b)->cb_arg) - - long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi, - long argl,long ret); - - typedef long (*callback)(BIO *b, int oper, const char *argp, - int argi, long argl, long retvalue); - -=head1 DESCRIPTION - -BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback, -they are both macros. The callback is called during most high level BIO -operations. It can be used for debugging purposes to trace operations on -a BIO or to modify its operation. - -BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be -used to set and retrieve an argument for use in the callback. - -BIO_debug_callback() is a standard debugging callback which prints -out information relating to each BIO operation. If the callback -argument is set if is interpreted as a BIO to send the information -to, otherwise stderr is used. - -callback() is the callback function itself. The meaning of each -argument is described below. - -The BIO the callback is attached to is passed in B<b>. - -B<oper> is set to the operation being performed. For some operations -the callback is called twice, once before and once after the actual -operation, the latter case has B<oper> or'ed with BIO_CB_RETURN. - -The meaning of the arguments B<argp>, B<argi> and B<argl> depends on -the value of B<oper>, that is the operation being performed. - -B<retvalue> is the return value that would be returned to the -application if no callback were present. The actual value returned -is the return value of the callback itself. In the case of callbacks -called before the actual BIO operation 1 is placed in retvalue, if -the return value is not positive it will be immediately returned to -the application and the BIO operation will not be performed. - -The callback should normally simply return B<retvalue> when it has -finished processing, unless if specifically wishes to modify the -value returned to the application. - -=head1 CALLBACK OPERATIONS - -=over 4 - -=item B<BIO_free(b)> - -callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the -free operation. - -=item B<BIO_read(b, out, outl)> - -callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before -the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue) -after. - -=item B<BIO_write(b, in, inl)> - -callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before -the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue) -after. - -=item B<BIO_gets(b, out, outl)> - -callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before the operation and -callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue) after. - -=item B<BIO_puts(b, in)> - -callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before -the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue) -after. - -=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)> - -callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and -callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after. - -=back - -=head1 EXAMPLE - -The BIO_debug_callback() function is a good example, its source is -in crypto/bio/bio_cb.c - -=cut diff --git a/lib/libssl/src/doc/crypto/BIO_should_retry.pod b/lib/libssl/src/doc/crypto/BIO_should_retry.pod deleted file mode 100644 index 3b7fc399975..00000000000 --- a/lib/libssl/src/doc/crypto/BIO_should_retry.pod +++ /dev/null @@ -1,112 +0,0 @@ -=pod - -=head1 NAME - -BIO_should_retry, BIO_should_read, BIO_should_write, -BIO_should_io_special, BIO_retry_type, -BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - #define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ) - #define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE) - #define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL) - #define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS) - #define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY) - - #define BIO_FLAGS_READ 0x01 - #define BIO_FLAGS_WRITE 0x02 - #define BIO_FLAGS_IO_SPECIAL 0x04 - #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL) - #define BIO_FLAGS_SHOULD_RETRY 0x08 - - BIO * BIO_get_retry_BIO(BIO *bio, int *reason); - int BIO_get_retry_reason(BIO *bio); - -=head1 DESCRIPTION - -These functions determine why a BIO is not able to read or write data. -They will typically be called after a failed BIO_read() or BIO_write() -call. - -BIO_should_retry() is true if the call that produced this condition -should then be retried at a later time. - -If BIO_should_retry() is false then the cause is an error condition. - -BIO_should_read() is true if the cause of the condition is that a BIO -needs to read data. - -BIO_should_write() is true if the cause of the condition is that a BIO -needs to read data. - -BIO_should_io_special() is true if some "special" condition, that is a -reason other than reading or writing is the cause of the condition. - -BIO_retry_type() returns a mask of the cause of a retry condition -consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>, -B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of -these. - -BIO_get_retry_BIO() determines the precise reason for the special -condition, it returns the BIO that caused this condition and if -B<reason> is not NULL it contains the reason code. The meaning of -the reason code and the action that should be taken depends on -the type of BIO that resulted in this condition. - -BIO_get_retry_reason() returns the reason for a special condition if -passed the relevant BIO, for example as returned by BIO_get_retry_BIO(). - -=head1 NOTES - -If BIO_should_retry() returns false then the precise "error condition" -depends on the BIO type that caused it and the return code of the BIO -operation. For example if a call to BIO_read() on a socket BIO returns -0 and BIO_should_retry() is false then the cause will be that the -connection closed. A similar condition on a file BIO will mean that it -has reached EOF. Some BIO types may place additional information on -the error queue. For more details see the individual BIO type manual -pages. - -If the underlying I/O structure is in a blocking mode almost all current -BIO types will not request a retry, because the underlying I/O -calls will not. If the application knows that the BIO type will never -signal a retry then it need not call BIO_should_retry() after a failed -BIO I/O call. This is typically done with file BIOs. - -SSL BIOs are the only current exception to this rule: they can request a -retry even if the underlying I/O structure is blocking, if a handshake -occurs during a call to BIO_read(). An application can retry the failed -call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY -on the underlying SSL structure. - -While an application may retry a failed non blocking call immediately -this is likely to be very inefficient because the call will fail -repeatedly until data can be processed or is available. An application -will normally wait until the necessary condition is satisfied. How -this is done depends on the underlying I/O structure. - -For example if the cause is ultimately a socket and BIO_should_read() -is true then a call to select() may be made to wait until data is -available and then retry the BIO operation. By combining the retry -conditions of several non blocking BIOs in a single select() call -it is possible to service several BIOs in a single thread, though -the performance may be poor if SSL BIOs are present because long delays -can occur during the initial handshake process. - -It is possible for a BIO to block indefinitely if the underlying I/O -structure cannot process or return any data. This depends on the behaviour of -the platforms I/O functions. This is often not desirable: one solution -is to use non blocking I/O and use a timeout on the select() (or -equivalent) call. - -=head1 BUGS - -The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O: -that is they cannot retry after a partial read or write. This is usually -worked around by only passing the relevant data to ASN1 functions when -the entire structure can be read or written. - -=cut |