287 lines
7.5 KiB
Groff
287 lines
7.5 KiB
Groff
.\" $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.
|