Document BIO_set_md_ctx(3) and BIO_C_SET_MD_CTX.

Correct the return types of some macros. Improve the RETURN VALUES section.
author: schwarze <> 2023-04-28 16:20:01 +0000
committer: schwarze <> 2023-04-28 16:20:01 +0000
commit: 1059b2a4a3d9eb72ad6073bbadee2edc0fd7f990 (patch)
tree: 810c1667807976df1f3c61c16b66e71e792e01b5 /src/lib
parent: 5b57d161ebef277ca538ff766787efeb3d1ff6bf (diff)
download: openbsd-1059b2a4a3d9eb72ad6073bbadee2edc0fd7f990.tar.gz
openbsd-1059b2a4a3d9eb72ad6073bbadee2edc0fd7f990.tar.bz2
openbsd-1059b2a4a3d9eb72ad6073bbadee2edc0fd7f990.zip
1 files changed, 84 insertions, 10 deletions
diff --git a/src/lib/libcrypto/man/BIO_f_md.3 b/src/lib/libcrypto/man/BIO_f_md.3
index 95ffbae783..279aabc980 100644
--- a/src/lib/libcrypto/man/BIO_f_md.3
+++ b/src/lib/libcrypto/man/BIO_f_md.3
@@ -1,7 +1,24 @@
-.\" $OpenBSD: BIO_f_md.3,v 1.14 2023/04/28 15:04:33 schwarze Exp $
+.\" $OpenBSD: BIO_f_md.3,v 1.15 2023/04/28 16:20:01 schwarze Exp $
-.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
+.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2022, 2023 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" 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 Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2000, 2006, 2009, 2016 The OpenSSL Project.
 .\" All rights reserved.
 .\"
@@ -56,7 +73,8 @@
 .Nm BIO_f_md ,
 .Nm BIO_set_md ,
 .Nm BIO_get_md ,
-.Nm BIO_get_md_ctx
+.Nm BIO_get_md_ctx ,
+.Nm BIO_set_md_ctx
 .Nd message digest BIO filter
 .Sh SYNOPSIS
 .In openssl/bio.h
@@ -65,21 +83,26 @@
 .Fo BIO_f_md
 .Fa void
 .Fc
-.Ft int
+.Ft long
 .Fo BIO_set_md
 .Fa "BIO *b"
 .Fa "EVP_MD *md"
 .Fc
-.Ft int
+.Ft long
 .Fo BIO_get_md
 .Fa "BIO *b"
 .Fa "EVP_MD **mdp"
 .Fc
-.Ft int
+.Ft long
 .Fo BIO_get_md_ctx
 .Fa "BIO *b"
 .Fa "EVP_MD_CTX **mdcp"
 .Fc
+.Ft long
+.Fo BIO_set_md_ctx
+.Fa "BIO *b"
+.Fa "EVP_MD_CTX *mdc"
+.Fc
 .Sh DESCRIPTION
 .Fn BIO_f_md
 returns the message digest BIO method.
@@ -164,6 +187,31 @@ is an internal context structure.
 Changes made to this context will affect the digest BIO itself, and
 the context pointer will become invalid when the digest BIO is freed.
 .Pp
+.Fn BIO_set_md_ctx
+replaces the digest context of
+.Fa b
+with
+.Fa mdc .
+Calling this function is usually not necessary
+because creating a digest BIO with
+.Xr BIO_new 3
+automatically creates a digest context and stores it internally.
+Before calling
+.Fn BIO_set_md_ctx ,
+the caller has to retrieve the old context using
+.Fn BIO_get_md_ctx ,
+and the caller also becomes responsible for calling
+.Xr EVP_MD_CTX_free 3
+on the old context.
+Unless
+.Fa mdc
+is already initialized, the caller needs to initialize it after calling
+.Fn BIO_set_md_ctx
+using either
+.Fn BIO_set_md
+or
+.Xr EVP_DigestInit 3 .
+.Pp
 When a chain containing a message digest BIO is copied with
 .Xr BIO_dup_chain 3 ,
 .Xr EVP_MD_CTX_copy_ex 3
@@ -172,6 +220,18 @@ from the existing BIO object to the new one,
 and the init flag that can be retrieved with
 .Xr BIO_get_init 3
 is set to 1.
+.Pp
+.Xr BIO_ctrl 3
+.Fa cmd
+arguments correspond to macros as follows:
+.Bl -column BIO_C_GET_MD_CTX "corresponding macro" -offset 3n
+.It Fa cmd No constant  Ta corresponding macro
+.It Dv BIO_C_GET_MD     Ta Fn BIO_get_md
+.It Dv BIO_C_GET_MD_CTX Ta Fn BIO_get_md_ctx
+.It Dv BIO_C_SET_MD     Ta Fn BIO_set_md
+.It Dv BIO_C_SET_MD_CTX Ta Fn BIO_set_md_ctx
+.It Dv BIO_CTRL_RESET   Ta Xr BIO_reset 3
+.El
 .Sh RETURN VALUES
 .Fn BIO_f_md
 returns the digest BIO method.
@@ -185,11 +245,21 @@ and
 returns a pointer to the static string
 .Qq message digest .
 .Pp
-.Fn BIO_set_md ,
+.Fn BIO_set_md
-.Fn BIO_get_md ,
+returns 1 on success or 0 if
+.Xr EVP_DigestInit_ex 3
+fails.
+.Pp
+.Fn BIO_get_md
 and
+.Fn BIO_set_md_ctx
+return 1 on success or 0 if
+.Fa b
+is not initialized.
+.Pp
 .Fn BIO_get_md_ctx
-return 1 for success and 0 for failure.
+returns 1 on success or 0 on failure,
+but the current implementation cannot actually fail.
 .Sh EXAMPLES
 The following example creates a BIO chain containing a SHA-1 and MD5
 digest BIO and passes the string "Hello World" through it.
@@ -270,6 +340,10 @@ first appeared in SSLeay 0.8.1.
 These functions have been available since
 .Ox 2.4 .
 .Pp
+.Fn BIO_set_md_ctx
+first appeared in OpenSSL 0.9.7e and has been available since
+.Ox 3.8 .
+.Pp
 Before OpenSSL 1.0.0, the call to
 .Fn BIO_get_md_ctx
 would only work if the
author	schwarze <>	2023-04-28 16:20:01 +0000
committer	schwarze <>	2023-04-28 16:20:01 +0000
commit	1059b2a4a3d9eb72ad6073bbadee2edc0fd7f990 (patch)
tree	810c1667807976df1f3c61c16b66e71e792e01b5 /src/lib
parent	5b57d161ebef277ca538ff766787efeb3d1ff6bf (diff)
download	openbsd-1059b2a4a3d9eb72ad6073bbadee2edc0fd7f990.tar.gz openbsd-1059b2a4a3d9eb72ad6073bbadee2edc0fd7f990.tar.bz2 openbsd-1059b2a4a3d9eb72ad6073bbadee2edc0fd7f990.zip

diff --git a/src/lib/libcrypto/man/BIO_f_md.3 b/src/lib/libcrypto/man/BIO_f_md.3 index 95ffbae783..279aabc980 100644 --- a/src/lib/libcrypto/man/BIO_f_md.3 +++ b/src/lib/libcrypto/man/BIO_f_md.3
@@ -1,7 +1,24 @@
1	.\" $OpenBSD: BIO_f_md.3,v 1.14 2023/04/28 15:04:33 schwarze Exp $	1	.\" $OpenBSD: BIO_f_md.3,v 1.15 2023/04/28 16:20:01 schwarze Exp $
2	.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400	2	.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
3	.\"	3	.\"
4	.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.	4	.\" This file is a derived work.
		5	.\" The changes are covered by the following Copyright and license:
		6	.\"
		7	.\" Copyright (c) 2022, 2023 Ingo Schwarze <schwarze@openbsd.org>
		8	.\"
		9	.\" Permission to use, copy, modify, and distribute this software for any
		10	.\" purpose with or without fee is hereby granted, provided that the above
		11	.\" copyright notice and this permission notice appear in all copies.
		12	.\"
		13	.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
		14	.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
		15	.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
		16	.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
		17	.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
		18	.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
		19	.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
		20	.\"
		21	.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
5	.\" Copyright (c) 2000, 2006, 2009, 2016 The OpenSSL Project.	22	.\" Copyright (c) 2000, 2006, 2009, 2016 The OpenSSL Project.
6	.\" All rights reserved.	23	.\" All rights reserved.
7	.\"	24	.\"
@@ -56,7 +73,8 @@
56	.Nm BIO_f_md ,	73	.Nm BIO_f_md ,
57	.Nm BIO_set_md ,	74	.Nm BIO_set_md ,
58	.Nm BIO_get_md ,	75	.Nm BIO_get_md ,
59	.Nm BIO_get_md_ctx	76	.Nm BIO_get_md_ctx ,
		77	.Nm BIO_set_md_ctx
60	.Nd message digest BIO filter	78	.Nd message digest BIO filter
61	.Sh SYNOPSIS	79	.Sh SYNOPSIS
62	.In openssl/bio.h	80	.In openssl/bio.h
@@ -65,21 +83,26 @@
65	.Fo BIO_f_md	83	.Fo BIO_f_md
66	.Fa void	84	.Fa void
67	.Fc	85	.Fc
68	.Ft int	86	.Ft long
69	.Fo BIO_set_md	87	.Fo BIO_set_md
70	.Fa "BIO *b"	88	.Fa "BIO *b"
71	.Fa "EVP_MD *md"	89	.Fa "EVP_MD *md"
72	.Fc	90	.Fc
73	.Ft int	91	.Ft long
74	.Fo BIO_get_md	92	.Fo BIO_get_md
75	.Fa "BIO *b"	93	.Fa "BIO *b"
76	.Fa "EVP_MD **mdp"	94	.Fa "EVP_MD **mdp"
77	.Fc	95	.Fc
78	.Ft int	96	.Ft long
79	.Fo BIO_get_md_ctx	97	.Fo BIO_get_md_ctx
80	.Fa "BIO *b"	98	.Fa "BIO *b"
81	.Fa "EVP_MD_CTX **mdcp"	99	.Fa "EVP_MD_CTX **mdcp"
82	.Fc	100	.Fc
		101	.Ft long
		102	.Fo BIO_set_md_ctx
		103	.Fa "BIO *b"
		104	.Fa "EVP_MD_CTX *mdc"
		105	.Fc
83	.Sh DESCRIPTION	106	.Sh DESCRIPTION
84	.Fn BIO_f_md	107	.Fn BIO_f_md
85	returns the message digest BIO method.	108	returns the message digest BIO method.
@@ -164,6 +187,31 @@ is an internal context structure.
164	Changes made to this context will affect the digest BIO itself, and	187	Changes made to this context will affect the digest BIO itself, and
165	the context pointer will become invalid when the digest BIO is freed.	188	the context pointer will become invalid when the digest BIO is freed.
166	.Pp	189	.Pp
		190	.Fn BIO_set_md_ctx
		191	replaces the digest context of
		192	.Fa b
		193	with
		194	.Fa mdc .
		195	Calling this function is usually not necessary
		196	because creating a digest BIO with
		197	.Xr BIO_new 3
		198	automatically creates a digest context and stores it internally.
		199	Before calling
		200	.Fn BIO_set_md_ctx ,
		201	the caller has to retrieve the old context using
		202	.Fn BIO_get_md_ctx ,
		203	and the caller also becomes responsible for calling
		204	.Xr EVP_MD_CTX_free 3
		205	on the old context.
		206	Unless
		207	.Fa mdc
		208	is already initialized, the caller needs to initialize it after calling
		209	.Fn BIO_set_md_ctx
		210	using either
		211	.Fn BIO_set_md
		212	or
		213	.Xr EVP_DigestInit 3 .
		214	.Pp
167	When a chain containing a message digest BIO is copied with	215	When a chain containing a message digest BIO is copied with
168	.Xr BIO_dup_chain 3 ,	216	.Xr BIO_dup_chain 3 ,
169	.Xr EVP_MD_CTX_copy_ex 3	217	.Xr EVP_MD_CTX_copy_ex 3
@@ -172,6 +220,18 @@ from the existing BIO object to the new one,
172	and the init flag that can be retrieved with	220	and the init flag that can be retrieved with
173	.Xr BIO_get_init 3	221	.Xr BIO_get_init 3
174	is set to 1.	222	is set to 1.
		223	.Pp
		224	.Xr BIO_ctrl 3
		225	.Fa cmd
		226	arguments correspond to macros as follows:
		227	.Bl -column BIO_C_GET_MD_CTX "corresponding macro" -offset 3n
		228	.It Fa cmd No constant Ta corresponding macro
		229	.It Dv BIO_C_GET_MD Ta Fn BIO_get_md
		230	.It Dv BIO_C_GET_MD_CTX Ta Fn BIO_get_md_ctx
		231	.It Dv BIO_C_SET_MD Ta Fn BIO_set_md
		232	.It Dv BIO_C_SET_MD_CTX Ta Fn BIO_set_md_ctx
		233	.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3
		234	.El
175	.Sh RETURN VALUES	235	.Sh RETURN VALUES
176	.Fn BIO_f_md	236	.Fn BIO_f_md
177	returns the digest BIO method.	237	returns the digest BIO method.
@@ -185,11 +245,21 @@ and
185	returns a pointer to the static string	245	returns a pointer to the static string
186	.Qq message digest .	246	.Qq message digest .
187	.Pp	247	.Pp
188	.Fn BIO_set_md ,	248	.Fn BIO_set_md
189	.Fn BIO_get_md ,	249	returns 1 on success or 0 if
		250	.Xr EVP_DigestInit_ex 3
		251	fails.
		252	.Pp
		253	.Fn BIO_get_md
190	and	254	and
		255	.Fn BIO_set_md_ctx
		256	return 1 on success or 0 if
		257	.Fa b
		258	is not initialized.
		259	.Pp
191	.Fn BIO_get_md_ctx	260	.Fn BIO_get_md_ctx
192	return 1 for success and 0 for failure.	261	returns 1 on success or 0 on failure,
		262	but the current implementation cannot actually fail.
193	.Sh EXAMPLES	263	.Sh EXAMPLES
194	The following example creates a BIO chain containing a SHA-1 and MD5	264	The following example creates a BIO chain containing a SHA-1 and MD5
195	digest BIO and passes the string "Hello World" through it.	265	digest BIO and passes the string "Hello World" through it.
@@ -270,6 +340,10 @@ first appeared in SSLeay 0.8.1.
270	These functions have been available since	340	These functions have been available since
271	.Ox 2.4 .	341	.Ox 2.4 .
272	.Pp	342	.Pp
		343	.Fn BIO_set_md_ctx
		344	first appeared in OpenSSL 0.9.7e and has been available since
		345	.Ox 3.8 .
		346	.Pp
273	Before OpenSSL 1.0.0, the call to	347	Before OpenSSL 1.0.0, the call to
274	.Fn BIO_get_md_ctx	348	.Fn BIO_get_md_ctx
275	would only work if the	349	would only work if the