1 files changed, 34 insertions, 1 deletions
diff --git a/src/lib/libcrypto/man/BIO_push.3 b/src/lib/libcrypto/man/BIO_push.3
index 413f8249a6..46c736e2c2 100644
--- a/src/lib/libcrypto/man/BIO_push.3
+++ b/src/lib/libcrypto/man/BIO_push.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_push.3,v 1.13 2022/12/16 13:41:55 schwarze Exp $
+.\" $OpenBSD: BIO_push.3,v 1.14 2022/12/16 16:02:17 schwarze Exp $
 .\" full merge up to:
 .\" OpenSSL doc/man3/BIO_push.pod 791bfd91 Nov 19 20:38:27 2021 +0100
 .\" OpenSSL doc/man7/bio.pod 1cb7eff4 Sep 10 13:56:40 2019 +0100
@@ -300,3 +300,36 @@ Both functions have been available since
 first appeared in OpenSSL 1.1.0
 and has been available since
 .Ox 7.1 .
+.Sh CAVEATS
+Creating a cyclic chain results in undefined behavior.
+For example, infinite recursion or infinite loops may ensue.
+.Pp
+If it is unknown whether
+.Fa b
+and
+.Fa new_tail
+are already members of the same chain and whether joining them would
+create a cycle, the calling code can use the following safe idiom:
+.Bd -literal -offset indent
+BIO *btest;
+for (btest = new_tail; btest != NULL; btest = BIO_next(btest))
+        if (btest == b)
+                /* Bail out because this would create a cycle. */
+BIO_push(b, new_tail);  /* This is now safe. */
+.Ed
+.Pp
+The same idiom can be used with
+.Fn BIO_set_next
+instead of
+.Fn BIO_push .
+.Pp
+Often, the safe idiom is not needed because it is already known that
+.Fa b
+and
+.Fa new_tail
+are not members of the same chain, for example when
+.Fa b
+or
+.Fa new_tail
+was created right before.

diff --git a/src/lib/libcrypto/man/BIO_push.3 b/src/lib/libcrypto/man/BIO_push.3 index 413f8249a6..46c736e2c2 100644 --- a/src/lib/libcrypto/man/BIO_push.3 +++ b/src/lib/libcrypto/man/BIO_push.3
@@ -1,4 +1,4 @@
1	.\" $OpenBSD: BIO_push.3,v 1.13 2022/12/16 13:41:55 schwarze Exp $	1	.\" $OpenBSD: BIO_push.3,v 1.14 2022/12/16 16:02:17 schwarze Exp $
2	.\" full merge up to:	2	.\" full merge up to:
3	.\" OpenSSL doc/man3/BIO_push.pod 791bfd91 Nov 19 20:38:27 2021 +0100	3	.\" OpenSSL doc/man3/BIO_push.pod 791bfd91 Nov 19 20:38:27 2021 +0100
4	.\" OpenSSL doc/man7/bio.pod 1cb7eff4 Sep 10 13:56:40 2019 +0100	4	.\" OpenSSL doc/man7/bio.pod 1cb7eff4 Sep 10 13:56:40 2019 +0100
@@ -300,3 +300,36 @@ Both functions have been available since
300	first appeared in OpenSSL 1.1.0	300	first appeared in OpenSSL 1.1.0
301	and has been available since	301	and has been available since
302	.Ox 7.1 .	302	.Ox 7.1 .
		303	.Sh CAVEATS
		304	Creating a cyclic chain results in undefined behavior.
		305	For example, infinite recursion or infinite loops may ensue.
		306	.Pp
		307	If it is unknown whether
		308	.Fa b
		309	and
		310	.Fa new_tail
		311	are already members of the same chain and whether joining them would
		312	create a cycle, the calling code can use the following safe idiom:
		313	.Bd -literal -offset indent
		314	BIO *btest;
		315
		316	for (btest = new_tail; btest != NULL; btest = BIO_next(btest))
		317	if (btest == b)
		318	/* Bail out because this would create a cycle. */
		319	BIO_push(b, new_tail); /* This is now safe. */
		320	.Ed
		321	.Pp
		322	The same idiom can be used with
		323	.Fn BIO_set_next
		324	instead of
		325	.Fn BIO_push .
		326	.Pp
		327	Often, the safe idiom is not needed because it is already known that
		328	.Fa b
		329	and
		330	.Fa new_tail
		331	are not members of the same chain, for example when
		332	.Fa b
		333	or
		334	.Fa new_tail
		335	was created right before.