Remove docs of various X509_TRUST "functionality" that no longer exists

Some macros are still exposed, but apart from the loss of a very nice way
of saying "this is completely misdesigned, overengineered and not properly
thought through" the only thing we would have learned from it is that this
stuff is "probably useless".

4 files changed, 5 insertions, 334 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 3bb9348af2..d4633edddf 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.288 2024/07/10 08:51:28 tb Exp $
+# $OpenBSD: Makefile,v 1.289 2024/08/17 09:16:37 tb Exp $
 
 .include <bsd.own.mk>
 
@@ -349,7 +349,6 @@ MAN=	\
         X509_STORE_new.3 \
         X509_STORE_set1_param.3 \
         X509_STORE_set_verify_cb_func.3 \
-        X509_TRUST_set.3 \
         X509_VERIFY_PARAM_new.3 \
         X509_VERIFY_PARAM_set_flags.3 \
         X509_add1_trust_object.3 \
diff --git a/src/lib/libcrypto/man/X509_TRUST_set.3 b/src/lib/libcrypto/man/X509_TRUST_set.3
deleted file mode 100644
index f363ead18b..0000000000
--- a/src/lib/libcrypto/man/X509_TRUST_set.3
+++ /dev/null
@@ -1,286 +0,0 @@
-.\" $OpenBSD: X509_TRUST_set.3,v 1.1 2021/07/24 14:33:14 schwarze Exp $
-.\"
-.\" Copyright (c) 2021 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.
-.\"
-.Dd $Mdocdate: July 24 2021 $
-.Dt X509_TRUST_SET 3
-.Os
-.Sh NAME
-.Nm X509_TRUST_set ,
-.Nm X509_TRUST_get_by_id ,
-.Nm X509_TRUST_add ,
-.Nm X509_TRUST_get_count ,
-.Nm X509_TRUST_cleanup ,
-.Nm X509_TRUST_get0 ,
-.Nm X509_TRUST_get_trust ,
-.Nm X509_TRUST_get0_name ,
-.Nm X509_TRUST_get_flags
-.Nd trust objects, indices, and identifiers
-.Sh SYNOPSIS
-.In openssl/x509.h
-.Ft int
-.Fo X509_TRUST_set
-.Fa "int *id_out"
-.Fa "int id_in"
-.Fc
-.Ft int
-.Fn X509_TRUST_get_by_id "int identifier"
-.Ft int
-.Fo X509_TRUST_add
-.Fa "int identifier"
-.Fa "int flags"
-.Fa "int (*check_trust)(X509_TRUST *, X509 *, int)"
-.Fa "const char *name"
-.Fa "int arg1"
-.Fa "void *arg2"
-.Fc
-.Ft int
-.Fn X509_TRUST_get_count void
-.Ft void
-.Fn X509_TRUST_cleanup void
-.Ft X509_TRUST *
-.Fn X509_TRUST_get0 "int index"
-.Ft int
-.Fn X509_TRUST_get_trust "const X509_TRUST *object"
-.Ft char *
-.Fn X509_TRUST_get0_name "const X509_TRUST *object"
-.Ft int
-.Fn X509_TRUST_get_flags "const X509_TRUST *object"
-.Sh DESCRIPTION
-The purposes that an X.509 certificate is trusted for
-can be identified in three equivalent ways:
-.Bl -enum
-.It
-By trust identifiers, which are positive integer constants.
-Standard trust identifiers lie in the range from
-.Dv X509_TRUST_MIN
-to
-.Dv X509_TRUST_MAX ,
-inclusive.
-User defined trust identifiers are larger than
-.Dv X509_TRUST_MAX .
-.It
-By trust indices, which are non-negative integer constants but
-differ from the trust identifiers expressing the same kind of trust.
-Standard trust indices are smaller than
-.Dv X509_TRUST_MAX .
-User defined trust indices are larger than or equal to
-.Dv X509_TRUST_MAX .
-.It
-By trust objects of the type
-.Vt X509_TRUST .
-Standard trust objects are available in static storage.
-User defined trust objects can be created with
-.Fn X509_TRUST_add .
-.El
-.Pp
-Application programmers cannot choose the way to identify kinds of trust
-that they like best; depending on the circumstances, all three ways
-are needed.
-Be warned that the naming of most functions is misleading.
-.Pp
-Most API functions documented outside the present manual page
-use trust identifiers rather than trust indices.
-.Pp
-ASN.1 object identifiers and NIDs provide a fourth and a fifth way
-to identify purposes that a certificate is trusted for.
-These are almost, but not exactly, equivalent
-to the three ways listed above; see the
-.Xr X509_check_trust 3
-manual for details.
-.Ss Using trust identifiers
-.Fn X509_TRUST_set
-validates the trust identifier
-.Fa id_in .
-If it is valid, it is copied to
-.Pf * Fa id_out .
-Otherwise,
-.Pf * Fa id_out
-remains unchanged.
-.Pp
-.Fn X509_TRUST_get_by_id
-converts the trust
-.Fa identifier
-to the corresponding trust
-.Fa index .
-To find the corresponding trust object, pass the result to
-.Fn X509_TRUST_get0 .
-.Pp
-.Fn X509_TRUST_add
-defines a purpose certificates can be trusted for with the given
-.Fa identifier
-or modifies its properties if it already exists.
-The trust
-.Fa identifier ,
-the
-.Fa flags ,
-the
-.Fa check_trust
-function, the
-.Fa name ,
-the number
-.Fa arg1 ,
-and the pointer
-.Fa arg2
-are copied into the
-.Vt X509_TRUST
-object.
-When modifying an existing trust object, previous
-values of fields are overwritten and a previous
-.Fa name
-string is freed if it was dynamically allocated.
-When creating a new trust object,
-it is added to the global array of user-defined trust objects.
-.Pp
-.Dv X509_TRUST_DYNAMIC
-and
-.Dv X509_TRUST_DYNAMIC_NAME
-are always ignored in the
-.Fa flags
-argument.
-.Dv X509_TRUST_DYNAMIC
-is automatically set if the object was created by the user.
-It is never set for standard objects,
-not even if they were modified by the user.
-.Dv X509_trust_DYNAMIC_NAME
-is automatically set if the object was created or modified by the user.
-It is only unset for unmodified standard objects.
-The library does not appear to define any other flags,
-so the flags argument is probably useless
-unless users define their own flags and use them in the
-.Fa check_trust
-function.
-.Pp
-The third and final argument of the
-.Fa check_trust
-function is the
-.Fa flags
-argument of
-.Fn X509_check_trust .
-.Pp
-The built-in trust checking functions documented in the
-.Xr X509_check_trust 3
-manual page use
-.Fa arg1
-as the corresponding ASN.1 object NID and ignore
-.Fa arg2
-and
-.Fa flags ,
-but a user-supplied
-.Fa check_trust
-function can use these fields in any arbitrary way.
-.Pp
-.Fn X509_TRUST_get_count
-returns the total number of trust objects currently existing,
-including both standard and user-defined objects.
-If no user-defined objects exist, the returned value is
-.Dv X509_TRUST_MAX .
-.Pp
-.Fn X509_TRUST_cleanup
-deletes all user-defined trust objects
-and invalidates their trust identifiers and trust indices.
-If any of the standard trust objects were modified by the user,
-those changes are
-.Em not
-reverted.
-.Ss Using trust indices
-.Fn X509_TRUST_get0
-converts the trust
-.Fa index
-to a pointer to the corresponding trust object.
-To find the corresponding trust identifier, pass the result to
-.Fn X509_TRUST_get_trust .
-.Ss Using trust objects
-.Fn X509_TRUST_get_trust
-converts a pointer to a trust
-.Fa object
-to the corresponding trust identifier.
-To find the corresponding trust index, pass the result to
-.Fn X509_TRUST_get_by_id .
-.Pp
-.Fn X509_TRUST_get0_name
-and
-.Fn X509_TRUST_get_flags
-retrieve the name and flags from the
-.Fa object ,
-respectively.
-.Sh RETURN VALUES
-.Fn X509_TRUST_set
-returns 1 if
-.Fa id_in
-is valid or 0 otherwise.
-.Pp
-.Fn X509_TRUST_get_by_id
-returns the corresponding trust index or -1 if the
-.Fa identifier
-is invalid.
-.Pp
-.Fn X509_TRUST_add
-returns 1 for success or 0 for failure.
-.Pp
-.Fn X509_TRUST_get_count
-returns the total number of trust objects currently existing.
-.Pp
-.Fn X509_TRUST_get0
-returns a standard or user-defined trust object or
-.Dv NULL
-if the
-.Fa index
-is invalid.
-.Pp
-.Fn X509_TRUST_get_trust
-always returns a valid trust identifier.
-.Pp
-.Fn X509_TRUST_get0_name
-returns a pointer to storage owned by the
-.Fa object .
-.Pp
-.Fn X509_TRUST_get_flags
-returns the flags associated with the
-.Fa object .
-.Sh ERRORS
-The following diagnostics can be retrieved with
-.Xr ERR_get_error 3 ,
-.Xr ERR_GET_REASON 3 ,
-and
-.Xr ERR_reason_error_string 3 :
-.Bl -tag -width Ds
-.It Dv X509_R_INVALID_TRUST Qq "invalid trust"
-.Fn X509_TRUST_set
-was called with an invalid
-.Fa id_in
-argument.
-.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure"
-.Fn X509_TRUST_add
-failed to allocate memory.
-.El
-.Pp
-The other functions provide no diagnostics.
-.Sh SEE ALSO
-.Xr X509_check_trust 3 ,
-.Xr X509_new 3 ,
-.Xr X509_PURPOSE_set 3 ,
-.Xr X509_VERIFY_PARAM_set_trust 3
-.Sh HISTORY
-.Fn X509_TRUST_set
-first appeared in OpenSSL 0.9.7 and has been available since
-.Ox 3.2 .
-.Pp
-The other functions first appeared in OpenSSL 0.9.5
-and have been available since
-.Ox 2.7 .
-.Sh CAVEATS
-The difference between trust identifiers and trust indices
-provides an ideal breeding ground for off-by-one bugs.
diff --git a/src/lib/libcrypto/man/X509_check_trust.3 b/src/lib/libcrypto/man/X509_check_trust.3
index 0f02a1b1ef..3a4e020950 100644
--- a/src/lib/libcrypto/man/X509_check_trust.3
+++ b/src/lib/libcrypto/man/X509_check_trust.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_check_trust.3,v 1.8 2023/04/30 14:49:47 tb Exp $
+.\" $OpenBSD: X509_check_trust.3,v 1.9 2024/08/17 09:16:37 tb Exp $
 .\"
 .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,12 +14,11 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: April 30 2023 $
+.Dd $Mdocdate: August 17 2024 $
 .Dt X509_CHECK_TRUST 3
 .Os
 .Sh NAME
 .Nm X509_check_trust ,
-.Nm X509_TRUST_set_default
 .Nd check whether a certificate is trusted
 .Sh SYNOPSIS
 .In openssl/x509.h
@@ -29,12 +28,6 @@
 .Fa "int trust"
 .Fa "int flags"
 .Fc
-.Ft int
-.Fo "(*X509_TRUST_set_default(int (*handler)(int, X509 *, int)))"
-.Fa "int trust"
-.Fa "X509 *certificate"
-.Fa "int flags"
-.Fc
 .Sh DESCRIPTION
 .Fn X509_check_trust
 checks whether the
@@ -183,27 +176,6 @@ identifiers listed above, or it may have installed additional,
 user-supplied checking functions for user-defined
 .Fa trust
 identifiers not listed above.
-.Pp
-If the function
-.Fn X509_TRUST_set_default
-was called, the
-.Fa handler
-function passed to it is used instead of the standard algorithm,
-but only in the case where the
-.Fa trust
-argument of
-.Fn X509_check_trust
-is invalid.
-The compatibility step is not used in this case.
-.Pp
-If the return value of the first call to
-.Fn X509_TRUST_set_default
-is saved and passed back to
-.Fn X509_TRUST_set_default
-later on, the standard behaviour
-of using the standard algorithm for invalid
-.Fa trust
-arguments is restored.
 .Sh RETURN VALUES
 .Fn X509_check_trust
 returns the following values:
@@ -222,27 +194,14 @@ The
 is neither trusted nor explicitly rejected,
 which implies that it is not trusted.
 .El
-.Pp
-.Fn X509_TRUST_set_default
-returns a pointer to the handler function for invalid
-.Fa trust
-that was installed before the call, which may either be a pointer
-to a function installed by a previous call to
-.Fn X509_TRUST_set_default
-or a pointer to the built-in function implementing the standard algorithm if
-.Fn X509_TRUST_set_default
-was never called before.
 .Sh SEE ALSO
 .Xr PEM_read_X509_AUX 3 ,
 .Xr X509_add1_trust_object 3 ,
 .Xr X509_CERT_AUX_new 3 ,
 .Xr X509_check_purpose 3 ,
 .Xr X509_new 3 ,
-.Xr X509_TRUST_set 3 ,
 .Xr X509_VERIFY_PARAM_set_trust 3
 .Sh HISTORY
 .Fn X509_check_trust
-and
-.Fn X509_TRUST_set_default
 first appeared in OpenSSL 0.9.5 and has been available since
 .Ox 2.7 .
diff --git a/src/lib/libcrypto/man/X509_new.3 b/src/lib/libcrypto/man/X509_new.3
index 3e7fb0a79f..9bc3ee95c8 100644
--- a/src/lib/libcrypto/man/X509_new.3
+++ b/src/lib/libcrypto/man/X509_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_new.3,v 1.43 2023/09/29 08:57:49 tb Exp $
+.\" $OpenBSD: X509_new.3,v 1.44 2024/08/17 09:16:37 tb Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file is a derived work.
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: September 29 2023 $
+.Dd $Mdocdate: August 17 2024 $
 .Dt X509_NEW 3
 .Os
 .Sh NAME
@@ -241,7 +241,6 @@ if an error occurs.
 .Xr X509_STORE_CTX_new 3 ,
 .Xr X509_STORE_get_by_subject 3 ,
 .Xr X509_STORE_new 3 ,
-.Xr X509_TRUST_set 3 ,
 .Xr X509v3_addr_add_inherit 3 ,
 .Xr X509v3_addr_get_range 3 ,
 .Xr X509v3_addr_inherits 3 ,