doc/bio.doc

   1 BIO Routines
   2
   3 This documentation is rather sparse, you are probably best
   4 off looking at the code for specific details.
   5
   6 The BIO library is a IO abstraction that was originally
   7 inspired by the need to have callbacks to perform IO to FILE
   8 pointers when using Windows 3.1 DLLs.  There are two types
   9 of BIO; a source/sink type and a filter type.
  10 The source/sink methods are as follows:
  11 -       BIO_s_mem()  memory buffer - a read/write byte array that
  12         grows until memory runs out :-).
  13 -       BIO_s_file()  FILE pointer - A wrapper around the normal
  14         'FILE *' commands, good for use with stdin/stdout.
  15 -       BIO_s_fd()  File descriptor - A wrapper around file
  16         descriptors, often used with pipes.
  17 -       BIO_s_socket()  Socket - Used around sockets.  It is
  18         mostly in the Microsoft world that sockets are different
  19         from file descriptors and there are all those ugly winsock
  20         commands.
  21 -       BIO_s_null()  Null - read nothing and write nothing.; a
  22         useful endpoint for filter type BIO's specifically things
  23         like the message digest BIO.
  24
  25 The filter types are
  26 -       BIO_f_buffer()  IO buffering - does output buffering into
  27         larger chunks and performs input buffering to allow gets()
  28         type functions.
  29 -       BIO_f_md()  Message digest - a transparent filter that can
  30         be asked to return a message digest for the data that has
  31         passed through it.
  32 -       BIO_f_cipher()  Encrypt or decrypt all data passing
  33         through the filter.
  34 -       BIO_f_base64()  Base64 decode on read and encode on write.
  35 -       BIO_f_ssl()  A filter that performs SSL encryption on the
  36         data sent through it.
  37
  38 Base BIO functions.
  39 The BIO library has a set of base functions that are
  40 implemented for each particular type.  Filter BIOs will
  41 normally call the equivalent function on the source/sink BIO
  42 that they are layered on top of after they have performed
  43 some modification to the data stream.  Multiple filter BIOs
  44 can be 'push' into a stack of modifers, so to read from a
  45 file, unbase64 it, then decrypt it, a BIO_f_cipher,
  46 BIO_f_base64 and a BIO_s_file would probably be used.  If a
  47 sha-1 and md5 message digest needed to be generated, a stack
  48 two BIO_f_md() BIOs and a BIO_s_null() BIO could be used.
  49 The base functions are
  50 -       BIO *BIO_new(BIO_METHOD *type); Create  a new BIO of  type 'type'.
  51 -       int BIO_free(BIO *a); Free a BIO structure.  Depending on
  52         the configuration, this will free the underlying data
  53         object for a source/sink BIO.
  54 -       int BIO_read(BIO *b, char *data, int len); Read upto 'len'
  55         bytes into 'data'.
  56 -       int BIO_gets(BIO *bp,char *buf, int size); Depending on
  57         the BIO, this can either be a 'get special' or a get one
  58         line of data, as per fgets();
  59 -       int BIO_write(BIO *b, char *data, int len); Write 'len'
  60         bytes from 'data' to the 'b' BIO.
  61 -       int BIO_puts(BIO *bp,char *buf); Either a 'put special' or
  62         a write null terminated string as per fputs().
  63 -       long BIO_ctrl(BIO *bp,int cmd,long larg,char *parg);  A
  64         control function which is used to manipulate the BIO
  65         structure and modify it's state and or report on it.  This
  66         function is just about never used directly, rather it
  67         should be used in conjunction with BIO_METHOD specific
  68         macros.
  69 -       BIO *BIO_push(BIO *new_top, BIO *old); new_top is apped to the
  70         top of the 'old' BIO list.  new_top should be a filter BIO.
  71         All writes will go through 'new_top' first and last on read.
  72         'old' is returned.
  73 -       BIO *BIO_pop(BIO *bio); the new topmost BIO is returned, NULL if
  74         there are no more.
  75
  76 If a particular low level BIO method is not supported
  77 (normally BIO_gets()), -2 will be returned if that method is
  78 called.  Otherwise the IO methods (read, write, gets, puts)
  79 will return the number of bytes read or written, and 0 or -1
  80 for error (or end of input).  For the -1 case,
  81 BIO_should_retry(bio) can be called to determine if it was a
  82 genuine error or a temporary problem.  -2 will also be
  83 returned if the BIO has not been initalised yet, in all
  84 cases, the correct error codes are set (accessible via the
  85 ERR library).
  86
  87
  88 The following functions are convenience functions:
  89 -       int BIO_printf(BIO *bio, char * format, ..);  printf but
  90         to a BIO handle.
  91 -       long BIO_ctrl_int(BIO *bp,int cmd,long larg,int iarg); a
  92         convenience function to allow a different argument types
  93         to be passed to BIO_ctrl().
  94 -       int BIO_dump(BIO *b,char *bytes,int len); output 'len'
  95         bytes from 'bytes' in a hex dump debug format.
  96 -       long BIO_debug_callback(BIO *bio, int cmd, char *argp, int
  97         argi, long argl, long ret) - a default debug BIO callback,
  98         this is mentioned below.  To use this one normally has to
  99         use the BIO_set_callback_arg() function to assign an
 100         output BIO for the callback to use.
 101 -       BIO *BIO_find_type(BIO *bio,int type); when there is a 'stack'
 102         of BIOs, this function scan the list and returns the first
 103         that is of type 'type', as listed in buffer.h under BIO_TYPE_XXX.
 104 -       void BIO_free_all(BIO *bio); Free the bio and all other BIOs
 105         in the list.  It walks the bio->next_bio list.
 106
 107
 108
 109 Extra commands are normally implemented as macros calling BIO_ctrl().
 110 -       BIO_number_read(BIO *bio) - the number of bytes processed
 111         by BIO_read(bio,.).
 112 -       BIO_number_written(BIO *bio) - the number of bytes written
 113         by BIO_write(bio,.).
 114 -       BIO_reset(BIO *bio) - 'reset' the BIO.
 115 -       BIO_eof(BIO *bio) - non zero if we are at the current end
 116         of input.
 117 -       BIO_set_close(BIO *bio, int close_flag) - set the close flag.
 118 -       BIO_get_close(BIO *bio) - return the close flag.
 119         BIO_pending(BIO *bio) - return the number of bytes waiting
 120         to be read (normally buffered internally).
 121 -       BIO_flush(BIO *bio) - output any data waiting to be output.
 122 -       BIO_should_retry(BIO *io) - after a BIO_read/BIO_write
 123         operation returns 0 or -1, a call to this function will
 124         return non zero if you should retry the call later (this
 125         is for non-blocking IO).
 126 -       BIO_should_read(BIO *io) - we should retry when data can
 127         be read.
 128 -       BIO_should_write(BIO *io) - we should retry when data can
 129         be written.
 130 -       BIO_method_name(BIO *io) - return a string for the method name.
 131 -       BIO_method_type(BIO *io) - return the unique ID of the BIO method.
 132 -       BIO_set_callback(BIO *io,  long (*callback)(BIO *io, int
 133         cmd, char *argp, int argi, long argl, long ret); - sets
 134         the debug callback.
 135 -       BIO_get_callback(BIO *io) - return the assigned function
 136         as mentioned above.
 137 -       BIO_set_callback_arg(BIO *io, char *arg)  - assign some
 138         data against the BIO.  This is normally used by the debug
 139         callback but could in reality be used for anything.  To
 140         get an idea of how all this works, have a look at the code
 141         in the default debug callback mentioned above.  The
 142         callback can modify the return values.
 143
 144 Details of the BIO_METHOD structure.
 145 typedef struct bio_method_st
 146         {
 147         int type;
 148         char *name;
 149         int (*bwrite)();
 150         int (*bread)();
 151         int (*bputs)();
 152         int (*bgets)();
 153         long (*ctrl)();
 154         int (*create)();
 155         int (*destroy)();
 156         } BIO_METHOD;
 157
 158 The 'type' is the numeric type of the BIO, these are listed in buffer.h;
 159 'Name' is a textual representation of the BIO 'type'.
 160 The 7 function pointers point to the respective function
 161 methods, some of which can be NULL if not implemented.
 162 The BIO structure
 163 typedef struct bio_st
 164         {
 165         BIO_METHOD *method;
 166         long (*callback)(BIO * bio, int mode, char *argp, int
 167                 argi, long argl, long ret);
 168         char *cb_arg; /* first argument for the callback */
 169         int init;
 170         int shutdown;
 171         int flags;      /* extra storage */
 172         int num;
 173         char *ptr;
 174         struct bio_st *next_bio; /* used by filter BIOs */
 175         int references;
 176         unsigned long num_read;
 177         unsigned long num_write;
 178         } BIO;
 179
 180 -       'Method' is the BIO method.
 181 -       'callback', when configured, is called before and after
 182         each BIO method is called for that particular BIO.  This
 183         is intended primarily for debugging and of informational feedback.
 184 -       'init' is 0 when the BIO can be used for operation.
 185         Often, after a BIO is created, a number of operations may
 186         need to be performed before it is available for use.  An
 187         example is for BIO_s_sock().  A socket needs to be
 188         assigned to the BIO before it can be used.
 189 -       'shutdown', this flag indicates if the underlying
 190         comunication primative being used should be closed/freed
 191         when the BIO is closed.
 192 -       'flags' is used to hold extra state.  It is primarily used
 193         to hold information about why a non-blocking operation
 194         failed and to record startup protocol information for the
 195         SSL BIO.
 196 -       'num' and 'ptr' are used to hold instance specific state
 197         like file descriptors or local data structures.
 198 -       'next_bio' is used by filter BIOs to hold the pointer of the
 199         next BIO in the chain. written data is sent to this BIO and
 200         data read is taken from it.
 201 -       'references' is used to indicate the number of pointers to
 202         this structure.  This needs to be '1' before a call to
 203         BIO_free() is made if the BIO_free() function is to
 204         actually free() the structure, otherwise the reference
 205         count is just decreased.  The actual BIO subsystem does
 206         not really use this functionality but it is useful when
 207         used in more advanced applicaion.
 208 -       num_read and num_write are the total number of bytes
 209         read/written via the 'read()' and 'write()' methods.
 210
 211 BIO_ctrl operations.
 212 The following is the list of standard commands passed as the
 213 second parameter to BIO_ctrl() and should be supported by
 214 all BIO as best as possible.  Some are optional, some are
 215 manditory, in any case, where is makes sense, a filter BIO
 216 should pass such requests to underlying BIO's.
 217 -       BIO_CTRL_RESET  - Reset the BIO back to an initial state.
 218 -       BIO_CTRL_EOF    - return 0 if we are not at the end of input,
 219         non 0 if we are.
 220 -       BIO_CTRL_INFO   - BIO specific special command, normal
 221         information return.
 222 -       BIO_CTRL_SET    - set IO specific parameter.
 223 -       BIO_CTRL_GET    - get IO specific parameter.
 224 -       BIO_CTRL_GET_CLOSE - Get the close on BIO_free() flag, one
 225         of BIO_CLOSE or BIO_NOCLOSE.
 226 -       BIO_CTRL_SET_CLOSE - Set the close on BIO_free() flag.
 227 -       BIO_CTRL_PENDING - Return the number of bytes available
 228         for instant reading
 229 -       BIO_CTRL_FLUSH  - Output pending data, return number of bytes output.
 230 -       BIO_CTRL_SHOULD_RETRY - After an IO error (-1 returned)
 231         should we 'retry' when IO is possible on the underlying IO object.
 232 -       BIO_CTRL_RETRY_TYPE - What kind of IO are we waiting on.
 233
 234 The following command is a special BIO_s_file() specific option.
 235 -       BIO_CTRL_SET_FILENAME - specify a file to open for IO.
 236
 237 The BIO_CTRL_RETRY_TYPE needs a little more explanation.
 238 When performing non-blocking IO, or say reading on a memory
 239 BIO, when no data is present (or cannot be written),
 240 BIO_read() and/or BIO_write() will return -1.
 241 BIO_should_retry(bio) will return true if this is due to an
 242 IO condition rather than an actual error.  In the case of
 243 BIO_s_mem(), a read when there is no data will return -1 and
 244 a should retry when there is more 'read' data.
 245 The retry type is deduced from 2 macros
 246 BIO_should_read(bio) and BIO_should_write(bio).
 247 Now while it may appear obvious that a BIO_read() failure
 248 should indicate that a retry should be performed when more
 249 read data is available, this is often not true when using
 250 things like an SSL BIO.  During the SSL protocol startup
 251 multiple reads and writes are performed, triggered by any
 252 SSL_read or SSL_write.
 253 So to write code that will transparently handle either a
 254 socket or SSL BIO,
 255         i=BIO_read(bio,..)
 256         if (I == -1)
 257                 {
 258                 if (BIO_should_retry(bio))
 259                         {
 260                         if (BIO_should_read(bio))
 261                                 {
 262                                 /* call us again when BIO can be read */
 263                                 }
 264                         if (BIO_should_write(bio))
 265                                 {
 266                                 /* call us again when BIO can be written */
 267                                 }
 268                         }
 269                 }
 270
 271 At this point in time only read and write conditions can be
 272 used but in the future I can see the situation for other
 273 conditions, specifically with SSL there could be a condition
 274 of a X509 certificate lookup taking place and so the non-
 275 blocking BIO_read would require a retry when the certificate
 276 lookup subsystem has finished it's lookup.  This is all
 277 makes more sense and is easy to use in a event loop type
 278 setup.
 279 When using the SSL BIO, either SSL_read() or SSL_write()s
 280 can be called during the protocol startup and things will
 281 still work correctly.
 282 The nice aspect of the use of the BIO_should_retry() macro
 283 is that all the errno codes that indicate a non-fatal error
 284 are encapsulated in one place.  The Windows specific error
 285 codes and WSAGetLastError() calls are also hidden from the
 286 application.
 287
 288 Notes on each BIO method.
 289 Normally buffer.h is just required but depending on the
 290 BIO_METHOD, ssl.h or evp.h will also be required.
 291
 292 BIO_METHOD *BIO_s_mem(void);
 293 -       BIO_set_mem_buf(BIO *bio, BUF_MEM *bm, int close_flag) -
 294         set the underlying BUF_MEM structure for the BIO to use.
 295 -       BIO_get_mem_ptr(BIO *bio, char **pp) - if pp is not NULL,
 296         set it to point to the memory array and return the number
 297         of bytes available.
 298 A read/write BIO.  Any data written is appended to the
 299 memory array and any read is read from the front.  This BIO
 300 can be used for read/write at the same time. BIO_gets() is
 301 supported in the fgets() sense.
 302 BIO_CTRL_INFO can be used to retrieve pointers to the memory
 303 buffer and it's length.
 304
 305 BIO_METHOD *BIO_s_file(void);
 306 -       BIO_set_fp(BIO *bio, FILE *fp, int close_flag) - set 'FILE *' to use.
 307 -       BIO_get_fp(BIO *bio, FILE **fp) - get the 'FILE *' in use.
 308 -       BIO_read_filename(BIO *bio, char *name) - read from file.
 309 -       BIO_write_filename(BIO *bio, char *name) - write to file.
 310 -       BIO_append_filename(BIO *bio, char *name) - append to file.
 311 This BIO sits over the normal system fread()/fgets() type
 312 functions. Gets() is supported.  This BIO in theory could be
 313 used for read and write but it is best to think of each BIO
 314 of this type as either a read or a write BIO, not both.
 315
 316 BIO_METHOD *BIO_s_socket(void);
 317 BIO_METHOD *BIO_s_fd(void);
 318 -       BIO_sock_should_retry(int i) - the underlying function
 319         used to determine if a call should be retried; the
 320         argument is the '0' or '-1' returned by the previous BIO
 321         operation.
 322 -       BIO_fd_should_retry(int i) - same as the
 323 -       BIO_sock_should_retry() except that it is different internally.
 324 -       BIO_set_fd(BIO *bio, int fd, int close_flag) - set the
 325         file descriptor to use
 326 -       BIO_get_fd(BIO *bio, int *fd) - get the file descriptor.
 327 These two methods are very similar.  Gets() is not
 328 supported, if you want this functionality, put a
 329 BIO_f_buffer() onto it.  This BIO is bi-directional if the
 330 underlying file descriptor is.  This is normally the case
 331 for sockets but not the case for stdio descriptors.
 332
 333 BIO_METHOD *BIO_s_null(void);
 334 Read and write as much data as you like, it all disappears
 335 into this BIO.
 336
 337 BIO_METHOD *BIO_f_buffer(void);
 338 -       BIO_get_buffer_num_lines(BIO *bio) - return the number of
 339         complete lines in the buffer.
 340 -       BIO_set_buffer_size(BIO *bio, long size) - set the size of
 341         the buffers.
 342 This type performs input and output buffering.  It performs
 343 both at the same time.  The size of the buffer can be set
 344 via the set buffer size option.  Data buffered for output is
 345 only written when the buffer fills.
 346
 347 BIO_METHOD *BIO_f_ssl(void);
 348 -       BIO_set_ssl(BIO *bio, SSL *ssl, int close_flag) - the SSL
 349         structure to use.
 350 -       BIO_get_ssl(BIO *bio, SSL **ssl) - get the SSL structure
 351         in use.
 352 The SSL bio is a little different from normal BIOs because
 353 the underlying SSL structure is a little different.  A SSL
 354 structure performs IO via a read and write BIO.  These can
 355 be different and are normally set via the
 356 SSL_set_rbio()/SSL_set_wbio() calls.  The SSL_set_fd() calls
 357 are just wrappers that create socket BIOs and then call
 358 SSL_set_bio() where the read and write BIOs are the same.
 359 The BIO_push() operation makes the SSLs IO BIOs the same, so
 360 make sure the BIO pushed is capable of two directional
 361 traffic.  If it is not, you will have to install the BIOs
 362 via the more conventional SSL_set_bio() call.  BIO_pop() will retrieve
 363 the 'SSL read' BIO.
 364
 365 BIO_METHOD *BIO_f_md(void);
 366 -       BIO_set_md(BIO *bio, EVP_MD *md) - set the message digest
 367         to use.
 368 -       BIO_get_md(BIO *bio, EVP_MD **mdp) - return the digest
 369         method in use in mdp, return 0 if not set yet.
 370 -       BIO_reset() reinitializes the digest (EVP_DigestInit())
 371         and passes the reset to the underlying BIOs.
 372 All data read or written via BIO_read() or BIO_write() to
 373 this BIO will be added to the calculated digest.  This
 374 implies that this BIO is only one directional.  If read and
 375 write operations are performed, two separate BIO_f_md() BIOs
 376 are reuqired to generate digests on both the input and the
 377 output.  BIO_gets(BIO *bio, char *md, int size) will place the
 378 generated digest into 'md' and return the number of bytes.
 379 The EVP_MAX_MD_SIZE should probably be used to size the 'md'
 380 array.  Reading the digest will also reset it.
 381
 382 BIO_METHOD *BIO_f_cipher(void);
 383 -       BIO_reset() reinitializes the cipher.
 384 -       BIO_flush() should be called when the last bytes have been
 385         output to flush the final block of block ciphers.
 386 -       BIO_get_cipher_status(BIO *b), when called after the last
 387         read from a cipher BIO, returns non-zero if the data
 388         decrypted correctly, otherwise, 0.
 389 -       BIO_set_cipher(BIO *b, EVP_CIPHER *c, unsigned char *key,
 390         unsigned char *iv, int encrypt)   This function is used to
 391         setup a cipher BIO.  The length of key and iv are
 392         specified by the choice of EVP_CIPHER.  Encrypt is 1 to
 393         encrypt and 0 to decrypt.
 394
 395 BIO_METHOD *BIO_f_base64(void);
 396 -       BIO_flush() should be called when the last bytes have been output.
 397 This BIO base64 encodes when writing and base64 decodes when
 398 reading.  It will scan the input until a suitable begin line
 399 is found.  After reading data, BIO_reset() will reset the
 400 BIO to start scanning again.  Do not mix reading and writing
 401 on the same base64 BIO.  It is meant as a single stream BIO.
 402
 403 Directions      type
 404 both            BIO_s_mem()
 405 one/both        BIO_s_file()
 406 both            BIO_s_fd()
 407 both            BIO_s_socket()
 408 both            BIO_s_null()
 409 both            BIO_f_buffer()
 410 one             BIO_f_md()
 411 one             BIO_f_cipher()
 412 one             BIO_f_base64()
 413 both            BIO_f_ssl()
 414
 415 It is easy to mix one and two directional BIOs, all one has
 416 to do is to keep two separate BIO pointers for reading and
 417 writing and be careful about usage of underlying BIOs.  The
 418 SSL bio by it's very nature has to be two directional but
 419 the BIO_push() command will push the one BIO into the SSL
 420 BIO for both reading and writing.
 421
 422 The best example program to look at is apps/enc.c and/or perhaps apps/dgst.c.
 423