purpose objects, indices, and
int trust, int flags,
int (*check_purpose)(const X509_PURPOSE *, const X509 *,
int), const char *name, const
char *sname, void *usr_data);
The purposes that an X.509 certificate is intended to be used for can be identified in three equivalent ways:
- By purpose identifiers, which are positive integer constants. Standard
purpose identifiers lie in the range from
X509_PURPOSE_MAX, inclusive, and are listed in the X509_check_purpose(3) manual page. User defined purpose identifiers are larger than
- By purpose indices, which are non-negative integer constants but differ
from the purpose identifiers for the same purpose. Standard purpose
indices are smaller than
X509_PURPOSE_MAX. User defined purpose indices are larger than or equal to
- By purpose objects of the type
X509_PURPOSE. Standard purpose objects are available
in static storage. User defined purpose objects can be created with
Application programmers cannot choose the way to identify purposes 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 purpose identifiers rather than purpose indices.
Using purpose identifiers
validates the purpose identifier id_in. If it is
valid, it is copied to *id_out. Otherwise,
*id_out remains unchanged.
converts the purpose identifier to the corresponding
purpose index. To find the corresponding purpose object, pass the result to
defines a purpose with the given identifier or
modifies its properties if it already exists. The purpose
identifier, the trust
identifier, the flags, the
check_purpose function, the
name, the short name sname, and
the usr_data pointer are copied into the
X509_PURPOSE object. When modifying an existing
purpose object, previous values of fields are overwritten and previous
name and sname strings are freed
if they were dynamically allocated. When creating a new purpose object, it
is added to the global array of user-defined purpose objects.
X509_PURPOSE_DYNAMIC_NAME are always ignored in the
X509_PURPOSE_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_PURPOSE_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
The third and final argument of the check_purpose function is the ca argument documented in X509_check_purpose(3).
returns the total number of purposes currently defined, including both
standard and user-defined purposes. If no user-defined purposes exist, the
returned value is
deletes all user-defined purpose objects and invalidates their purpose
identifiers and purpose indices. If any of the standard purpose objects were
modified by the user, those changes are
Using purpose indices
converts the purpose index to a pointer to the
corresponding purpose object. To find the corresponding purpose identifier,
pass the result to
returns the lowest index of a purpose with the given short name.
Using purpose objects
converts a pointer to a purpose object to the
corresponding purpose identifier. To find the corresponding purpose index,
pass the result to
retrieve the name, short name, and trust identifier from the
X509_PURPOSE_set() returns 1 if
id_in is valid or 0 otherwise.
X509_PURPOSE_get_by_sname() return the corresponding
purpose index or -1 if no matching purpose is found.
X509_PURPOSE_add() returns 1 for success
or 0 for failure.
X509_PURPOSE_get_count() returns the total
number of purposes currently defined.
X509_PURPOSE_get0() returns a standard or
user-defined purpose object or
NULL if the
index is invalid.
X509_PURPOSE_get_id() always returns a
valid purpose identifier.
X509_PURPOSE_get0_sname() return pointers to storage
owned by the object.
X509_PURPOSE_get_trust() returns the trust
identifier 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_PURPOSE_set() was called with an invalid id_in argument.
X509V3_R_INVALID_NULL_ARGUMENT"invalid null argument"
X509_PURPOSE_add() was called with a name or sname argument of
X509_PURPOSE_add() failed to allocate memory.
The other functions provide no diagnostics.
X509_check_purpose(3), X509_new(3), X509_STORE_set_purpose(3), X509_VERIFY_PARAM_set_purpose(3)
X509_PURPOSE_set() first appeared in
OpenSSL 0.9.7 and has been available since OpenBSD
The other functions first appeared in OpenSSL 0.9.5 and have been available since OpenBSD 2.7.
The difference between purpose identifiers and purpose indices provides an ideal breeding ground for off-by-one bugs.