path: root/lib/libcrypto/man/X509_TRUST_set.3

.\" $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.