From d2e2508d543829c28b3f43d75543ff7ce9221aa1 Mon Sep 17 00:00:00 2001 From: schwarze Date: Sat, 17 Feb 2018 23:24:38 +0000 Subject: [PATCH] In bio.h rev. 1.31 2018/02/17 13:57:14, tb@ provided new functions BIO_meth_*(). Import the documentation from OpenSSL, with extensive tweaks by me. --- lib/libcrypto/man/BIO_ctrl.3 | 5 +- lib/libcrypto/man/BIO_meth_new.3 | 269 +++++++++++++++++++++++++++++++ lib/libcrypto/man/BIO_new.3 | 5 +- lib/libcrypto/man/BIO_read.3 | 5 +- lib/libcrypto/man/Makefile | 3 +- 5 files changed, 280 insertions(+), 7 deletions(-) create mode 100644 lib/libcrypto/man/BIO_meth_new.3 diff --git a/lib/libcrypto/man/BIO_ctrl.3 b/lib/libcrypto/man/BIO_ctrl.3 index 7d1c5da6003..d4392dd3d2a 100644 --- a/lib/libcrypto/man/BIO_ctrl.3 +++ b/lib/libcrypto/man/BIO_ctrl.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: BIO_ctrl.3,v 1.7 2017/08/01 14:57:03 schwarze Exp $ +.\" $OpenBSD: BIO_ctrl.3,v 1.8 2018/02/17 23:24:38 schwarze Exp $ .\" OpenSSL b055fceb Thu Oct 20 09:56:18 2016 +0100 .\" .\" This file was written by Dr. Stephen Henson . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: August 1 2017 $ +.Dd $Mdocdate: February 17 2018 $ .Dt BIO_CTRL 3 .Os .Sh NAME @@ -308,6 +308,7 @@ Source/sink BIOs return an 0 if they do not recognize the .Fn BIO_ctrl operation. .Sh SEE ALSO +.Xr BIO_meth_new 3 , .Xr BIO_new 3 .Sh BUGS Some of the return values are ambiguous and care should be taken. diff --git a/lib/libcrypto/man/BIO_meth_new.3 b/lib/libcrypto/man/BIO_meth_new.3 new file mode 100644 index 00000000000..d50b7ffc767 --- /dev/null +++ b/lib/libcrypto/man/BIO_meth_new.3 @@ -0,0 +1,269 @@ +.\" $OpenBSD: BIO_meth_new.3,v 1.1 2018/02/17 23:24:38 schwarze Exp $ +.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" The original file was written by Matt Caswell +.\" Copyright (c) 2016 The OpenSSL Project. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" 3. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: February 17 2018 $ +.Dt BIO_METH_NEW 3 +.Os +.Sh NAME +.Nm BIO_meth_new , +.Nm BIO_meth_free , +.Nm BIO_meth_set_write , +.Nm BIO_meth_set_read , +.Nm BIO_meth_set_puts , +.Nm BIO_meth_set_ctrl , +.Nm BIO_meth_set_create , +.Nm BIO_meth_set_destroy +.Nd manipulate BIO_METHOD structures +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO_METHOD * +.Fo BIO_meth_new +.Fa "int type" +.Fa "const char *name" +.Fc +.Ft void +.Fo BIO_meth_free +.Fa "BIO_METHOD *biom" +.Fc +.Ft int +.Fo BIO_meth_set_write +.Fa "BIO_METHOD *biom" +.Fa "int (*write)(BIO *, const char *, int)" +.Fc +.Ft int +.Fo BIO_meth_set_read +.Fa "BIO_METHOD *biom" +.Fa "int (*read)(BIO *, char *, int)" +.Fc +.Ft int +.Fo BIO_meth_set_puts +.Fa "BIO_METHOD *biom" +.Fa "int (*puts)(BIO *, const char *)" +.Fc +.Ft int +.Fo BIO_meth_set_ctrl +.Fa "BIO_METHOD *biom" +.Fa "long (*ctrl)(BIO *, int, long, void *)" +.Fc +.Ft int +.Fo BIO_meth_set_create +.Fa "BIO_METHOD *biom" +.Fa "int (*create)(BIO *)" +.Fc +.Ft int +.Fo BIO_meth_set_destroy +.Fa "BIO_METHOD *biom" +.Fa "int (*destroy)(BIO *)" +.Fc +.Sh DESCRIPTION +The +.Vt BIO_METHOD +structure stores function pointers implementing a +.Vt BIO +type. +See +.Xr BIO_new 3 +for more information about +.Vt BIO +objects. +.Pp +.Fn BIO_meth_new +creates a new +.Vt BIO_METHOD +structure. +It requires a unique integer +.Fa type . +The +.Fa name +pointer is stored in the structure and will not be freed by +.Fn BIO_meth_free . +.Pp +The standard BIO types are listed in +.In openssl/bio.h . +Some examples include +.Dv BIO_TYPE_BUFFER +and +.Dv BIO_TYPE_CIPHER . +The +.Fa type +of filter BIOs should have the +.Dv BIO_TYPE_FILTER +bit set. +Source/sink BIOs should have the +.Dv BIO_TYPE_SOURCE_SINK +bit set. +File descriptor based BIOs (e.g. socket, fd, connect, accept etc.\&) +should additionally have the +.Dv BIO_TYPE_DESCRIPTOR +bit set. +See +.Xr BIO_find_type 3 +for more information. +.Pp +.Fn BIO_meth_free +is an alias for +.Xr free 3 . +.Pp +.Fn BIO_meth_set_write +and +.Fn BIO_meth_set_read +set the functions +.Fa write +and +.Fa read +used for writing and reading arbitrary length data to and from the +.Vt BIO . +These functions are called from +.Xr BIO_write 3 +and +.Xr BIO_read 3 , +respectively. +The parameters and return values of +.Fa write +and +.Fa read +have the same meaning as for +.Xr BIO_write 3 +and +.Xr BIO_read 3 . +.Pp +.Fn BIO_meth_set_puts +sets the function +.Fa puts +used for writing a NUL-terminated string to the +.Vt BIO . +This function is called from +.Xr BIO_puts 3 . +The parameters and the return value of +.Fa puts +have the same meaning as for +.Xr BIO_puts 3 . +.Pp +.Fn BIO_meth_set_ctrl +sets the function +.Fa ctrl +used for processing control messages in the +.Vt BIO . +This function is called from +.Xr BIO_ctrl 3 . +The parameters and return value of +.Fa ctrl +have the same meaning as for +.Xr BIO_ctrl 3 . +.Pp +.Fn BIO_meth_set_create +sets a function +.Fa create +used while initializing a new instance of the +.Vt BIO . +This function is called from +.Xr BIO_new 3 . +The +.Xr BIO_new 3 +function allocates the memory for the new +.Vt BIO , +and a pointer to this newly allocated structure is passed +as the parameter to +.Fa create . +.Pp +.Fn BIO_meth_set_destroy +sets a function +.Fa destroy +used while destroying an instance of a +.Vt BIO . +This function is called from +.Xr BIO_free 3 . +A pointer to the +.Vt BIO +to be destroyed is passed as the parameter. +The +.Fa destroy +function is intended to perform clean-up specific to the +.Vt BIO +.Fa type . +The memory for the +.Vt BIO +itself must not be freed by this function. +.Sh RETURN VALUES +.Fn BIO_meth_new +returns the new +.Vt BIO_METHOD +structure or +.Dv NULL +if an error occurs. +.Pp +The +.Fn BIO_meth_set_* +functions return 1 on success or 0 on error. +Currently, they cannot fail. +.Sh SEE ALSO +.Xr BIO_ctrl 3 , +.Xr BIO_find_type 3 , +.Xr BIO_new 3 , +.Xr BIO_read 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.0. diff --git a/lib/libcrypto/man/BIO_new.3 b/lib/libcrypto/man/BIO_new.3 index 356986d76d9..cdf15278bfe 100644 --- a/lib/libcrypto/man/BIO_new.3 +++ b/lib/libcrypto/man/BIO_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: BIO_new.3,v 1.8 2017/03/25 17:15:59 schwarze Exp $ +.\" $OpenBSD: BIO_new.3,v 1.9 2018/02/17 23:24:38 schwarze Exp $ .\" OpenSSL doc/man3/BIO_new.pod ca3a82c3 Mar 25 11:31:18 2015 -0400 .\" OpenSSL doc/man7/bio.pod a9c85cea Nov 11 09:33:55 2016 +0100 .\" @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 25 2017 $ +.Dd $Mdocdate: February 17 2018 $ .Dt BIO_NEW 3 .Os .Sh NAME @@ -192,6 +192,7 @@ Create a memory BIO: .Xr BIO_f_ssl 3 , .Xr BIO_find_type 3 , .Xr BIO_get_ex_new_index 3 , +.Xr BIO_meth_new 3 , .Xr BIO_printf 3 , .Xr BIO_push 3 , .Xr BIO_read 3 , diff --git a/lib/libcrypto/man/BIO_read.3 b/lib/libcrypto/man/BIO_read.3 index 2da3728237f..a58c1fa5ff4 100644 --- a/lib/libcrypto/man/BIO_read.3 +++ b/lib/libcrypto/man/BIO_read.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: BIO_read.3,v 1.5 2016/12/06 14:45:08 schwarze Exp $ +.\" $OpenBSD: BIO_read.3,v 1.6 2018/02/17 23:24:38 schwarze Exp $ .\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" .\" This file was written by Dr. Stephen Henson . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 6 2016 $ +.Dd $Mdocdate: February 17 2018 $ .Dt BIO_READ 3 .Os .Sh NAME @@ -165,5 +165,6 @@ 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. .Sh SEE ALSO +.Xr BIO_meth_new 3 , .Xr BIO_new 3 , .Xr BIO_should_retry 3 diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 77a65196856..431285c7e0c 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.130 2018/02/17 16:59:48 schwarze Exp $ +# $OpenBSD: Makefile,v 1.131 2018/02/17 23:24:38 schwarze Exp $ .include @@ -26,6 +26,7 @@ MAN= \ BIO_f_null.3 \ BIO_find_type.3 \ BIO_get_ex_new_index.3 \ + BIO_meth_new.3 \ BIO_new.3 \ BIO_printf.3 \ BIO_push.3 \ -- 2.20.1