.\" $OpenBSD: X509_TRUST_set.3,v 1.1 2021/07/24 14:33:14 schwarze Exp $ .\" .\" Copyright (c) 2021 Ingo Schwarze .\" .\" 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.