NAME

X509_TRUST_set, X509_TRUST_get_by_id, X509_TRUST_add, X509_TRUST_get_count, X509_TRUST_cleanup, X509_TRUST_get0, X509_TRUST_get_trust, X509_TRUST_get0_name, X509_TRUST_get_flags — trust objects, indices, and identifiers

SYNOPSIS

#include <openssl/x509.h> int
X509_TRUST_set(int *id_out, int id_in); int
X509_TRUST_get_by_id(int identifier); int
X509_TRUST_add(int identifier, int flags, int (*check_trust)(X509_TRUST *, X509 *, int), const char *name, int arg1, void *arg2); int
X509_TRUST_get_count(void); void
X509_TRUST_cleanup(void); X509_TRUST *
X509_TRUST_get0(int index); int
X509_TRUST_get_trust(const X509_TRUST *object); char *
X509_TRUST_get0_name(const X509_TRUST *object); int
X509_TRUST_get_flags(const X509_TRUST *object);

DESCRIPTION

The purposes that an X.509 certificate is trusted for can be identified in three equivalent ways:

1. By trust identifiers, which are positive integer constants. Standard trust identifiers lie in the range from X509_TRUST_MIN to X509_TRUST_MAX, inclusive. User defined trust identifiers are larger than X509_TRUST_MAX.
2. 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 X509_TRUST_MAX.
3. By trust objects of the type X509_TRUST. Standard trust objects are available in static storage. User defined trust objects can be created with X509_TRUST_add().

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

X509_TRUST_set() validates the trust identifier id_in. If it is valid, it is copied to *id_out. Otherwise, *id_out remains unchanged. X509_TRUST_get_by_id() converts the trust identifier to the corresponding trust index. To find the corresponding trust object, pass the result to X509_TRUST_get0(). X509_TRUST_add() 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 and X509_TRUST_DYNAMIC_NAME are always ignored in the flags argument. 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 X509_check_trust(). 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. 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 X509_TRUST_MAX. 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 not reverted.

Using trust indices

X509_TRUST_get0() converts the trust index to a pointer to the corresponding trust object. To find the corresponding trust identifier, pass the result to X509_TRUST_get_trust().

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 X509_TRUST_get_by_id(). X509_TRUST_get0_name() and X509_TRUST_get_flags() retrieve the name and flags from the object, respectively.

RETURN VALUES

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 invalid. 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.

ERRORS

The following diagnostics can be retrieved with ERR_get_error(3), ERR_GET_REASON(3), and ERR_reason_error_string(3):

X509_R_INVALID_TRUST “invalid trust”

X509_TRUST_set() was called with an invalid id_in argument.

ERR_R_MALLOC_FAILURE “malloc failure”

X509_TRUST_add() failed to allocate memory.

The other functions provide no diagnostics.

SEE ALSO

X509_check_trust(3), X509_new(3), X509_PURPOSE_set(3), X509_VERIFY_PARAM_set_trust(3)

HISTORY

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.

CAVEATS

The difference between trust identifiers and trust indices provides an ideal breeding ground for off-by-one bugs.