---
name: "libressl-X509_PURPOSE_set"
section: "3"
platform: "linux"
package: "libressl"
version: "4.4.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libressl-X509_PURPOSE_set"
---

# libressl-X509\_PURPOSE\_set(3)

purpose objects, indices, and identifiers

## NAME

**X509\_PURPOSE\_set**, **X509\_PURPOSE\_get\_by\_id**, **X509\_PURPOSE\_add**, **X509\_PURPOSE\_get\_count**, **X509\_PURPOSE\_cleanup**, **X509\_PURPOSE\_get0**, **X509\_PURPOSE\_get\_by\_sname**, **X509\_PURPOSE\_get\_id**, **X509\_PURPOSE\_get0\_name**, **X509\_PURPOSE\_get0\_sname**, **X509\_PURPOSE\_get\_trust** – purpose objects, indices, and identifiers

## SYNOPSIS

Crypto Library (libcrypto, -lcrypto)

**#include \<openssl/x509v3.h\>**

*int*\

**X509\_PURPOSE\_set**(*int \*id\_out*, *int id\_in*);

*int*\

**X509\_PURPOSE\_get\_by\_id**(*int identifier*);

*int*\

**X509\_PURPOSE\_add**(*int identifier*, *int trust*, *int flags*, *int (\*check\_purpose)(const X509\_PURPOSE \*, const X509 \*, int)*, *const char \*name*, *const char \*sname*, *void \*usr\_data*);

*int*\

**X509\_PURPOSE\_get\_count**(*void*);

*void*\

**X509\_PURPOSE\_cleanup**(*void*);

*X509\_PURPOSE* *\**\

**X509\_PURPOSE\_get0**(*int index*);

*int*\

**X509\_PURPOSE\_get\_by\_sname**(*const char \*sname*);

*int*\

**X509\_PURPOSE\_get\_id**(*const X509\_PURPOSE \*object*);

*char* *\**\

**X509\_PURPOSE\_get0\_name**(*const X509\_PURPOSE \*object*);

*char* *\**\

**X509\_PURPOSE\_get0\_sname**(*const X509\_PURPOSE \*object*);

*int*\

**X509\_PURPOSE\_get\_trust**(*const X509\_PURPOSE \*object*);

## DESCRIPTION

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

1. By purpose identifiers, which are positive integer constants. Standard purpose identifiers lie in the range from X509\_PURPOSE\_MIN to X509\_PURPOSE\_MAX, inclusive, and are listed in the X509\_check\_purpose(3) manual page. User defined purpose identifiers are larger than X509\_PURPOSE\_MAX.

2. 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 X509\_PURPOSE\_MAX.

3. By purpose objects of the type *X509\_PURPOSE*. Standard purpose objects are available in static storage. User defined purpose objects can be created with **X509\_PURPOSE\_add**().

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

**X509\_PURPOSE\_set**() validates the purpose identifier *id\_in*. If it is valid, it is copied to \**id\_out*. Otherwise, \**id\_out* remains unchanged.

**X509\_PURPOSE\_get\_by\_id**() converts the purpose *identifier* to the corresponding purpose index. To find the corresponding purpose object, pass the result to **X509\_PURPOSE\_get0**().

**X509\_PURPOSE\_add**() 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 and X509\_PURPOSE\_DYNAMIC\_NAME are always ignored in the *flags* argument. 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 *check\_purpose* function.

The third and final argument of the *check\_purpose* function is the *ca* argument documented in X509\_check\_purpose(3).

**X509\_PURPOSE\_get\_count**() 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 X509\_PURPOSE\_MAX.

**X509\_PURPOSE\_cleanup**() 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 *not* reverted.

### Using purpose indices

**X509\_PURPOSE\_get0**() converts the purpose *index* to a pointer to the corresponding purpose object. To find the corresponding purpose identifier, pass the result to **X509\_PURPOSE\_get\_id**().

**X509\_PURPOSE\_get\_by\_sname**() returns the lowest index of a purpose with the given short name.

### Using purpose objects

**X509\_PURPOSE\_get\_id**() converts a pointer to a purpose *object* to the corresponding purpose identifier. To find the corresponding purpose index, pass the result to **X509\_PURPOSE\_get\_by\_id**().

**X509\_PURPOSE\_get0\_name**(), **X509\_PURPOSE\_get0\_sname**(), and **X509\_PURPOSE\_get\_trust**() retrieve the name, short name, and trust identifier from the *object*, respectively.

## RETURN VALUES

**X509\_PURPOSE\_set**() returns 1 if *id\_in* is valid or 0 otherwise.

**X509\_PURPOSE\_get\_by\_id**() and **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\_name**() and **X509\_PURPOSE\_get0\_sname**() return pointers to storage owned by the *object*.

**X509\_PURPOSE\_get\_trust**() returns the trust identifier 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):

- X509V3\_R\_INVALID\_PURPOSE "invalid purpose"

  **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 NULL.

- ERR\_R\_MALLOC\_FAILURE "malloc failure"

  **X509\_PURPOSE\_add**() failed to allocate memory.

The other functions provide no diagnostics.

## SEE ALSO

X509\_check\_purpose(3), X509\_new(3), X509\_STORE\_set\_purpose(3), X509\_VERIFY\_PARAM\_set\_purpose(3)

## HISTORY

**X509\_PURPOSE\_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 purpose identifiers and purpose indices provides an ideal breeding ground for off-by-one bugs.