Remove X509_STORE_CTX_purpose_inherit(3) documentation

This abomination of an API will be removed. Remove the hairy details of
its internals and make the documentation of X509_STORE_CTX_set_trust(3)
and X509_STORE_CTX_set_purpose(3) independent of it.

Neither of these two remaining APIs can be recommended. Once set, trust
and purpose are sticky. Setting the trust to a different (valid) value
will indicate success but leave the value unchanged. I suppose it means
the new trust value was successfully ignored. Also, setting the trust to
X509_TRUST_DEFAULT can succeed or fail depending on which OpenSSL
derivative you use. Setting the purpose will also set the trust (unless
it is already set). Setting some purposes may or may not fail depending
on the OpenSSL lib.

The only way you have a chance of knowing what will be set is by calling
only one of these functions directly after X509_STORE_CTX_init(). This
isn't really safe either because in some versions the user can override
the values stored in a global table by writing directly to it.

The actual contributions here are rather minimal. State more explicitly
that 0 is invalid (but results in success being returned), document the
error values to be accurate across implementations and call out some of
the nonsense in a CAVEATS section.

Many thanks to schwarze for the very helpful review with lots of input.

ok schwarze

diff --git a/lib/libcrypto/man/X509_STORE_CTX_set_flags.3 b/lib/libcrypto/man/X509_STORE_CTX_set_flags.3
index 2ac7695..db991bd 100644 (file)
--- a/lib/libcrypto/man/X509_STORE_CTX_set_flags.3
+++ b/lib/libcrypto/man/X509_STORE_CTX_set_flags.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_STORE_CTX_set_flags.3,v 1.6 2021/11/17 16:08:32 schwarze Exp $
+.\" $OpenBSD: X509_STORE_CTX_set_flags.3,v 1.7 2024/01/12 19:28:02 tb Exp $
 .\" full merge up to: OpenSSL aae41f8c Jun 25 09:47:15 2015 +0100
 .\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
@@ -67,7 +67,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 17 2021 $
+.Dd $Mdocdate: January 12 2024 $
 .Dt X509_STORE_CTX_SET_FLAGS 3
 .Os
 .Sh NAME
@@ -76,7 +76,8 @@
 .Nm X509_STORE_CTX_set_depth ,
 .Nm X509_STORE_CTX_set_trust ,
 .Nm X509_STORE_CTX_set_purpose ,
-.Nm X509_STORE_CTX_purpose_inherit ,
+.\" .Nm X509_STORE_CTX_purpose_inherit is intentionally undocumented
+.\" because it will be removed in the next major bump.
 .Nm X509_STORE_CTX_get0_param ,
 .Nm X509_STORE_CTX_set0_param ,
 .Nm X509_STORE_CTX_set_default
@@ -109,13 +110,6 @@
 .Fa "X509_STORE_CTX *ctx"
 .Fa "int purpose"
 .Fc
-.Ft int
-.Fo X509_STORE_CTX_purpose_inherit
-.Fa "X509_STORE_CTX *ctx"
-.Fa "int def_purpose"
-.Fa "int purpose"
-.Fa "int trust"
-.Fc
 .Ft X509_VERIFY_PARAM *
 .Fo X509_STORE_CTX_get0_param
 .Fa "X509_STORE_CTX *ctx"
@@ -178,9 +172,6 @@ argument is 0 or invalid
 or the trust identifier is already set to a non-zero value in the
 .Vt X509_VERIFY_PARAM
 object, no action occurs.
-Here and in the following,
-.Dv X509_TRUST_DEFAULT
-counts as invalid.
 .Pp
 .Fn X509_STORE_CTX_set_purpose
 sets the
@@ -200,7 +191,7 @@ is called the
 .Pp
 The function fails if the
 .Fa purpose
-argument or the associated trust is not 0 but invalid; otherwise,
+argument or the associated trust is invalid but not 0; otherwise,
 .Fn X509_STORE_CTX_set_purpose
 also does the equivalent of calling
 .Fn X509_STORE_CTX_set_trust
@@ -212,62 +203,6 @@ object, it is not changed, even if the
 .Fa purpose
 argument is valid, too.
 .Pp
-.Fn X509_STORE_CTX_purpose_inherit
-is similar to
-.Fn X509_STORE_CTX_set_purpose ,
-with the following modifications:
-.Bl -bullet
-.It
-If the
-.Fa purpose
-argument is 0,
-.Fa def_purpose
-is used instead.
-.It
-If the associated trust is
-.Dv X509_TRUST_DEFAULT ,
-the trust associated with
-.Fa def_purpose
-is used instead, or if
-.Fa def_purpose
-is 0 or invalid, the function fails.
-.It
-If the
-.Fa trust
-argument is not 0, it is used instead of the associated trust,
-and the equivalent of calling
-.Fn X509_STORE_CTX_set_trust
-is done even if both
-.Fa purpose
-and
-.Fa def_purpose
-are 0.
-Even if the
-.Fa trust
-argument is not 0, if the (then unused) associated trust is
-.Dv X509_TRUST_DEFAULT ,
-.Fa def_purpose
-is still required to be valid.
-.El
-.Pp
-Note that, even if all arguments are valid and the return value is 1,
-it is possible that nothing changed, or that only either one of the
-purpose and trust identifiers were set, or that both were set.
-It can also happen that the purpose identifier gets set according to the
-.Fa purpose
-argument, but the trust identifier gets set according to the
-.Fa def_purpose
-argument in the same call.
-.Pp
-The intended way of using this function is to pass the purpose and
-trust attributes of another structure of an arbitrary type as the
-.Fa purpose
-and
-.Fa trust
-arguments, and to provide
-.Fa def_purpose
-as a fallback in case the settings in the other structure are incomplete.
-.Pp
 .Fn X509_STORE_CTX_get0_param
 retrieves an internal pointer to the verification parameters associated
 with
@@ -293,7 +228,7 @@ and copies them using
 .Fn X509_STORE_CTX_set_trust
 returns 1 if the
 .Fa trust
-argument is 0 or valid or 0 if it is not 0 but invalid.
+argument is 0 or valid or 0 if it is invalid but not 0.
 A return value of 1 does
 .Em not
 imply that the trust identifier stored in the
@@ -306,45 +241,9 @@ returns 1 if both the
 argument and the associated trust are 0 or valid.
 It returns 0 if either the
 .Fa purpose
-argument or the associated trust is not 0 but invalid.
+argument or the associated trust is invalid but not 0.
 A return value of 1 does not imply that any data was changed.
 .Pp
-.Fn X509_STORE_CTX_purpose_inherit
-returns 0 if:
-.Bl -bullet
-.It
-The
-.Fa purpose
-argument is not 0 and invalid.
-.It
-The
-.Fa purpose
-argument is 0 and the
-.Fa def_purpose
-argument is not 0 and invalid.
-.It
-The associated trust is
-.Dv X509_TRUST_DEFAULT
-and the
-.Fa def_purpose
-argument is 0 or invalid,
-or the trust identifier associated with it is not 0 but invalid.
-.It
-The
-.Fa trust
-argument is not 0 and invalid.
-.It
-The
-.Fa trust
-argument is 0 and the associated trust is neither 0 nor
-.Dv X509_TRUST_DEFAULT
-but invalid.
-.El
-.Pp
-Otherwise,
-.Fn X509_STORE_CTX_purpose_inherit
-returns 1, which does not imply that any data was changed.
-.Pp
 .Fn X509_STORE_CTX_get0_param
 returns a pointer to an
 .Vt X509_VERIFY_PARAM
@@ -355,37 +254,26 @@ if an error occurred.
 .Fn X509_STORE_CTX_set_default
 returns 1 for success or 0 if an error occurred.
 .Sh ERRORS
-For
-.Fn X509_STORE_CTX_set_trust ,
-.Fn X509_STORE_CTX_set_purpose ,
-and
-.Fn X509_STORE_CTX_purpose_inherit ,
-the following diagnostics can be retrieved with
+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_UNKNOWN_TRUST_ID Qq "unknown trust id"
-The
+.Fn X509_STORE_CTX_set_trust
+was called with a
 .Fa trust
-argument or the trust identifier associated with
+argument that is invalid but not 0.
+Other implementations may also return this when
+.Fn X509_STORE_CTX_set_purpose
+is called with a
 .Fa purpose
-or
-.Fa def_purpose
-is not 0 but invalid,
+argument with invalid associated trust.
 .It Dv X509_R_UNKNOWN_PURPOSE_ID Qq "unknown purpose id"
 The
 .Fa purpose
-argument is not 0 and invalid.
-Or it is 0 and the
-.Fa def_purpose
-argument is not 0 and invalid.
-Or the associated trust is
-.Dv X509_TRUST_DEFAULT
-and
-.Fa def_purpose
-is 0 or invalid.
+argument is invalid but not 0.
 .El
 .Pp
 The other functions provide no diagnostics.
@@ -405,10 +293,9 @@ The other functions provide no diagnostics.
 first appeared in OpenSSL 0.9.3 and has been available since
 .Ox 2.4 .
 .Pp
-.Fn X509_STORE_CTX_set_trust ,
-.Fn X509_STORE_CTX_set_purpose ,
+.Fn X509_STORE_CTX_set_trust
 and
-.Fn X509_STORE_CTX_purpose_inherit
+.Fn X509_STORE_CTX_set_purpose
 first appeared in OpenSSL 0.9.5 and have been available since
 .Ox 2.7 .
 .Pp
@@ -424,3 +311,26 @@ and
 .Fn X509_STORE_CTX_set_default
 first appeared in OpenSSL 0.9.8 and have been available since
 .Ox 4.5 .
+.Sh CAVEATS
+The precise effect of a successful call to
+.Fn X509_STORE_CTX_set_trust
+and
+.Fn X509_STORE_CTX_set_purpose
+is unclear unless only one of these functions is used immediately after
+.Xr X509_STORE_CTX_init 3 .
+It is therefore recommended to use
+.Fn X509_STORE_CTX_get0_param ,
+.Xr X509_VERIFY_PARAM_set_trust 3 ,
+and
+.Xr X509_VERIFY_PARAM_set_purpose 3
+instead.
+.Pp
+The confusingly named
+.Dv X509_TRUST_DEFAULT
+is less than
+.Dv X509_TRUST_MIN
+and different implementations treat it as valid or invalid
+when used as an associated trust or as a
+.Fa trust
+argument for
+.Fn X509_STORE_CTX_set_trust .