generic-library/openssl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add documentation for BIO functions

Browse Source 
Add the documentation for new BIO functions added as a result of
making BIO and BIO_METHOD opaque.

Reviewed-by: Richard Levitte <levitte@openssl.org>
This commit is contained in:
Matt Caswell 2016-03-29 14:25:23 +01:00
parent 1737552558
commit 85556b4dec
4 changed files with 204 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
doc/crypto/BIO_get_data.pod Normal file
View File

@ -0,0 +1,56 @@
=pod
=head1 NAME
BIO_set_data, BIO_get_data, BIO_set_init, BIO_get_init, BIO_set_shutdown,
BIO_get_shutdown - functions for managing BIO state information
=head1 SYNOPSIS
#include <openssl/bio.h>
void BIO_set_data(BIO *a, void *ptr);
void *BIO_get_data(BIO *a);
void BIO_set_init(BIO *a, int init);
int BIO_get_init(BIO *a);
void BIO_set_shutdown(BIO *a, int shut);
int BIO_get_shutdown(BIO *a);
=head1 DESCRIPTION
These functions are mainly useful when implementing a custom BIO.
The BIO_set_data() function associates the custom data pointed to by B<ptr> with
the BIO. This data can subsequently be retrieved via a call to BIO_get_data().
This can be used by custom BIOs for storing implementation specific information.
The BIO_set_init() function sets the value of the BIO's "init" flag to indicate
whether initialisation has been completed for this BIO or not. A non-zero value
indicates that initialisation is complete, whilst zero indicates that it is not.
Often initialisation will complete during initial construction of the BIO. For
some BIOs however, initialisation may not complete until after additional steps
have occurred (for example through calling custom ctrls). The BIO_get_init()
function returns the value of the "init" flag.
The BIO_set_shutdown() and BIO_get_shutdown() functions set and get the state of
this BIO's shutdown (i.e. BIO_CLOSE) flag. If set then the underlying resource
is also closed when the BIO is freed.
=head1 RETURN VALUES
BIO_get_data() returns a pointer to the implementation specific custom data
associated with this BIO, or NULL if none has been set.
BIO_get_init() returns the state of the BIO's init flag.
BIO_get_shutdown() returns the stat of the BIO's shutdown (i.e. BIO_CLOSE) flag.
=head1 SEE ALSO
L<bio>, L<BIO_meth_new>
=head1 HISTORY
The functions described here were added in OpenSSL version 1.1.0.
=cut

117
doc/crypto/BIO_meth_new.pod Normal file
View File

@ -0,0 +1,117 @@
=pod
=head1 NAME
BIO_meth_new, BIO_meth_free, BIO_meth_get_write, BIO_meth_set_write,
BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts,
BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl,
BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy,
BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,
BIO_meth_set_callback_ctrl - Routines to build up BIO methods
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD *BIO_meth_new(int type, const char *name);
void BIO_meth_free(BIO_METHOD *biom);
int (*BIO_meth_get_write(BIO_METHOD *biom)) (BIO *, const char *, int);
int BIO_meth_set_write(BIO_METHOD *biom,
int (*write) (BIO *, const char *, int));
int (*BIO_meth_get_read(BIO_METHOD *biom)) (BIO *, char *, int);
int BIO_meth_set_read(BIO_METHOD *biom,
int (*read) (BIO *, char *, int));
int (*BIO_meth_get_puts(BIO_METHOD *biom)) (BIO *, const char *);
int BIO_meth_set_puts(BIO_METHOD *biom,
int (*puts) (BIO *, const char *));
int (*BIO_meth_get_gets(BIO_METHOD *biom)) (BIO *, char *, int);
int BIO_meth_set_gets(BIO_METHOD *biom,
int (*gets) (BIO *, char *, int));
long (*BIO_meth_get_ctrl(BIO_METHOD *biom)) (BIO *, int, long, void *);
int BIO_meth_set_ctrl(BIO_METHOD *biom,
long (*ctrl) (BIO *, int, long, void *));
int (*BIO_meth_get_create(BIO_METHOD *bion)) (BIO *);
int BIO_meth_set_create(BIO_METHOD *biom, int (*create) (BIO *));
int (*BIO_meth_get_destroy(BIO_METHOD *biom)) (BIO *);
int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy) (BIO *));
long (*BIO_meth_get_callback_ctrl(BIO_METHOD *biom))
(BIO *, int, bio_info_cb *);
int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,
long (*callback_ctrl) (BIO *, int,
bio_info_cb *));
=head1 DESCRIPTION
The B<BIO_METHOD> type is a structure used for the implementation of new BIO
types. It provides a set of of functions used by OpenSSL for the implementation
of the various BIO capabilities. See the L<bio> page for more information.
BIO_meth_new() creates a new B<BIO_METHOD> structure. It should be given a
unique integer B<type> and a string that represents its B<name>. The set of
standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples
include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a
type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs
should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor
based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the
"descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type> page for
more information.
BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
associated with it.
BIO_meth_get_write() and BIO_meth_set_write() get and set the function used for
writing arbitrary length data to the BIO respectively. This function will be
called in response to the application calling BIO_write(). The parameters for
the function have the same meaning as for BIO_write().
BIO_meth_get_read() and BIO_meth_set_read() get and set the function used for
reading arbitrary length data from the BIO respectively. This function will be
called in response to the application calling BIO_read(). The parameters for the
function have the same meaning as for BIO_read().
BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for
writing a NULL terminated string to the BIO respectively. This function will be
called in response to the application calling BIO_puts(). The parameters for
the function have the same meaning as for BIO_puts().
BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically
used for reading a line of data from the BIO respectively (see the L<BIO_gets>
page for more information). This function will be called in response to the
application calling BIO_gets(). The parameters for the function have the same
meaning as for BIO_gets().
BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for
processing ctrl messages in the BIO respectively. See the L<BIO_ctrl> page for
more information. This function will be called in response to the application
calling BIO_ctrl(). The parameters for the function have the same meaning as for
BIO_ctrl().
BIO_meth_get_create() and BIO_meth_set_create() get and set the function used
for creating a new instance of the BIO respectively. This function will be
called in response to the application calling BIO_new() or BIO_set() and passing
in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the
memory for the new BIO, and a pointer to this newly allocated structure will
be passed as a parameter to the function.
BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used
for destroying an instance of a BIO respectively. This function will be
called in response to the application calling BIO_free(). A pointer to the BIO
to be destroyed is passed as a parameter. The destroy function should be used
for BIO specific clean up. The memory for the BIO itself should not be freed by
this function.
BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the
function used for processing callback ctrl messages in the BIO respectively. See
the L<BIO_callback_ctrl> page for more information. This function will be called
in response to the application calling BIO_callback_ctrl(). The parameters for
the function have the same meaning as for BIO_callback_ctrl().
=head1 SEE ALSO
L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read>, L<BIO_new>
=head1 HISTORY
The functions described here were added in OpenSSL version 1.1.0.
=cut

19
doc/crypto/BIO_push.pod
View File

@ -2,14 +2,15 @@
=head1 NAME =head1 NAME
BIO_push, BIO_pop - add and remove BIOs from a chain. BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain.
=head1 SYNOPSIS =head1 SYNOPSIS
#include <openssl/bio.h> #include <openssl/bio.h>
BIO * BIO_push(BIO *b,BIO *append); BIO *BIO_push(BIO *b,BIO *append);
BIO * BIO_pop(BIO *b); BIO *BIO_pop(BIO *b);
void BIO_set_next(BIO *b, BIO *next);
=head1 DESCRIPTION =head1 DESCRIPTION
@ -21,6 +22,10 @@ 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, becomes a single BIO with no association with the original chain,
it can thus be freed or attached to a different chain. it can thus be freed or attached to a different chain.
BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to
by B<next>. The new chain may include some of the same BIOs from the old chain
or it may be completely different.
=head1 NOTES =head1 NOTES
The names of these functions are perhaps a little misleading. BIO_push() The names of these functions are perhaps a little misleading. BIO_push()
@ -66,4 +71,10 @@ BIO.
=head1 SEE ALSO =head1 SEE ALSO
TBA L<bio>
=head1 HISTORY
The BIO_set_next() function was added in OpenSSL version 1.1.0.
=cut

20
doc/crypto/BIO_should_retry.pod
View File

@ -4,7 +4,8 @@
BIO_should_retry, BIO_should_read, BIO_should_write, BIO_should_retry, BIO_should_read, BIO_should_write,
BIO_should_io_special, BIO_retry_type, BIO_should_retry, BIO_should_io_special, BIO_retry_type, BIO_should_retry,
BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry
functions
=head1 SYNOPSIS =head1 SYNOPSIS
@ -22,8 +23,9 @@ BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions
#define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL) #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)
#define BIO_FLAGS_SHOULD_RETRY 0x08 #define BIO_FLAGS_SHOULD_RETRY 0x08
BIO * BIO_get_retry_BIO(BIO *bio, int *reason); BIO *BIO_get_retry_BIO(BIO *bio, int *reason);
int BIO_get_retry_reason(BIO *bio); int BIO_get_retry_reason(BIO *bio);
void BIO_set_retry_reason(BIO *bio, int reason);
=head1 DESCRIPTION =head1 DESCRIPTION
@ -59,6 +61,9 @@ the type of BIO that resulted in this condition.
BIO_get_retry_reason() returns the reason for a special condition if 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(). passed the relevant BIO, for example as returned by BIO_get_retry_BIO().
BIO_set_retry_reason() sets the retry reason for a special condition for a given
BIO. This would usually only be called by BIO implementations.
=head1 NOTES =head1 NOTES
If BIO_should_retry() returns false then the precise "error condition" If BIO_should_retry() returns false then the precise "error condition"
@ -111,4 +116,11 @@ the entire structure can be read or written.
=head1 SEE ALSO =head1 SEE ALSO
TBA L<bio>
=head1 HISTORY
The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in
OpenSSL version 1.1.0.
=cut