+++ /dev/null
-.\" $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.
-.\" $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>
.\"
.\" 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
.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
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:
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 .
projects / openbsd / commitdiff