Document X509_STORE_CTX_set_trust(3), X509_STORE_CTX_set_purpose(3),

and X509_STORE_CTX_purpose_inherit(3).  These functions look deceptively
simple on first sight, but their semantics is surprisingly complicated.

diff --git a/lib/libcrypto/man/X509_STORE_CTX_set_flags.3 b/lib/libcrypto/man/X509_STORE_CTX_set_flags.3
index d84b1e7..7247927 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.2 2021/07/22 19:44:30 schwarze Exp $
+.\" $OpenBSD: X509_STORE_CTX_set_flags.3,v 1.3 2021/07/25 14:05:03 schwarze 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,13 +67,16 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 22 2021 $
+.Dd $Mdocdate: July 25 2021 $
 .Dt X509_STORE_CTX_SET_FLAGS 3
 .Os
 .Sh NAME
 .Nm X509_STORE_CTX_set_flags ,
 .Nm X509_STORE_CTX_set_time ,
 .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_get0_param ,
 .Nm X509_STORE_CTX_set0_param ,
 .Nm X509_STORE_CTX_set_default
@@ -96,6 +99,23 @@
 .Fa "X509_STORE_CTX *ctx"
 .Fa "int depth"
 .Fc
+.Ft int
+.Fo X509_STORE_CTX_set_trust
+.Fa "X509_STORE_CTX *ctx"
+.Fa "int trust"
+.Fc
+.Ft int
+.Fo X509_STORE_CTX_set_purpose
+.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"
@@ -132,17 +152,122 @@ for a description of the verification flags.
 .Pp
 .Fn X509_STORE_CTX_set_time
 sets the verification
-.Fa time .
+.Fa time
+using
+.Xr X509_VERIFY_PARAM_set_time 3 .
 The
 .Fa dummy
 argument is ignored.
 .Pp
 .Fn X509_STORE_CTX_set_depth
 sets the maximum verification
-.Fa depth .
+.Fa depth
+using
+.Xr X509_VERIFY_PARAM_set_depth 3 .
 That is the maximum number of untrusted CA certificates
 that can appear in a chain.
 .Pp
+.Fn X509_STORE_CTX_set_trust
+sets the
+.Fa trust
+identifier that can also be set using
+.Xr X509_VERIFY_PARAM_set_trust 3 .
+If the
+.Fa trust
+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
+.Fa purpose
+identifier that can also be set using
+.Xr X509_VERIFY_PARAM_set_purpose 3 .
+If the
+.Fa purpose
+argument is 0 or any failure occurs, nothing is changed.
+.Pp
+In the following, the trust identifier contained in the
+.Vt X509_PURPOSE
+object associated with
+.Fa purpose
+is called the
+.Dq associated trust .
+.Pp
+The function fails if the
+.Fa purpose
+argument or the associated trust is not 0 but invalid; otherwise,
+.Fn X509_STORE_CTX_set_purpose
+also does the equivalent of calling
+.Fn X509_STORE_CTX_set_trust
+with the associated trust.
+.Pp
+If the purpose identifier is already set to a non-zero value in the
+.Vt X509_VERIFY_PARAM
+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
@@ -163,6 +288,61 @@ This uses the function
 to find an appropriate set of parameters from
 .Fa name .
 .Sh RETURN VALUES
+.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.
+A return value of 1 does
+.Em not
+imply that the trust identifier stored in the
+.Vt X509_VERIFY_PARAM
+object was changed.
+.Pp
+.Fn X509_STORE_CTX_set_purpose
+returns 1 if both the
+.Fa purpose
+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.
+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
@@ -172,6 +352,41 @@ if an error occurred.
 .Pp
 .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
+.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
+.Fa trust
+argument or the trust identifier associated with
+.Fa purpose
+or
+.Fa def_purpose
+is not 0 but invalid,
+.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.
+.El
+.Pp
+The other functions provide no diagnostics.
 .Sh SEE ALSO
 .Xr X509_STORE_CTX_get_error 3 ,
 .Xr X509_STORE_CTX_new 3 ,
@@ -184,6 +399,13 @@ returns 1 for success or 0 if an error occurred.
 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 ,
+and
+.Fn X509_STORE_CTX_purpose_inherit
+first appeared in OpenSSL 0.9.5 and have been available since
+.Ox 2.7 .
+.Pp
 .Fn X509_STORE_CTX_set_flags
 and
 .Fn X509_STORE_CTX_set_time