trust objects, indices, and
int flags, int
(*check_trust)(X509_TRUST *, X509 *, int), const char
*name, int arg1, void
The purposes that an X.509 certificate is trusted for can be identified in three equivalent ways:
- By trust identifiers, which are positive integer constants. Standard trust
identifiers lie in the range from
X509_TRUST_MAX, inclusive. User defined trust identifiers are larger than
- 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
X509_TRUST_MAX. User defined trust indices are larger than or equal to
- By trust objects of the type
X509_TRUST. Standard trust objects are available in
static storage. User defined trust objects can be created with
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.
Most API functions documented outside the present manual page use trust identifiers rather than trust indices.
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 X509_check_trust(3) manual for details.
Using trust identifiers
validates the trust identifier id_in. If it is valid,
it is copied to *id_out. Otherwise,
*id_out remains unchanged.
converts the trust identifier to the corresponding
trust index. To find the corresponding trust object,
pass the result to
defines a purpose certificates can be trusted for with the given
identifier or modifies its properties if it already
exists. The trust identifier, the
flags, the check_trust function,
the name, the number arg1, and
the pointer arg2 are copied into the
X509_TRUST object. When modifying an existing trust
object, previous values of fields are overwritten and a previous
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.
X509_TRUST_DYNAMIC_NAME are always ignored in the
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.
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 check_trust function.
The third and final argument of the
check_trust function is the
flags argument of
The built-in trust checking functions documented in the X509_check_trust(3) manual page use arg1 as the corresponding ASN.1 object NID and ignore arg2 and flags, but a user-supplied check_trust function can use these fields in any arbitrary way.
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
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
Using trust indices
converts the trust index to a pointer to the
corresponding trust object. To find the corresponding trust identifier, pass
the result to
Using trust objects
X509_TRUST_get_trust() converts a pointer
to a trust object to the corresponding trust
identifier. To find the corresponding trust index, pass the result to
retrieve the name and flags from the object,
X509_TRUST_set() returns 1 if
id_in is valid or 0 otherwise.
X509_TRUST_get_by_id() returns the
corresponding trust index or -1 if the identifier is
X509_TRUST_add() returns 1 for success or
0 for failure.
X509_TRUST_get_count() returns the total
number of trust objects currently existing.
X509_TRUST_get0() returns a standard or
user-defined trust object or
NULL if the
index is invalid.
X509_TRUST_get_trust() always returns a
valid trust identifier.
X509_TRUST_get0_name() returns a pointer
to storage owned by the object.
X509_TRUST_get_flags() returns the flags
associated with the object.
The following diagnostics can be retrieved with ERR_get_error(3), ERR_GET_REASON(3), and ERR_reason_error_string(3):
X509_TRUST_set() was called with an invalid id_in argument.
X509_TRUST_add() failed to allocate memory.
The other functions provide no diagnostics.
X509_check_trust(3), X509_new(3), X509_PURPOSE_set(3), X509_VERIFY_PARAM_set_trust(3)
X509_TRUST_set() first appeared in OpenSSL
0.9.7 and has been available since OpenBSD 3.2.
The other functions first appeared in OpenSSL 0.9.5 and have been available since OpenBSD 2.7.
The difference between trust identifiers and trust indices provides an ideal breeding ground for off-by-one bugs.