X509_NAME_ENTRY_GET_OBJECT(3) | Library Functions Manual | X509_NAME_ENTRY_GET_OBJECT(3)

# NAME

`X509_NAME_ENTRY_new`, `X509_NAME_ENTRY_free`, `X509_NAME_ENTRY_get_object`, `X509_NAME_ENTRY_get_data`, `X509_NAME_ENTRY_set`, `X509_NAME_ENTRY_set_object`, `X509_NAME_ENTRY_set_data`, `X509_NAME_ENTRY_create_by_txt`, `X509_NAME_ENTRY_create_by_NID`, `X509_NAME_ENTRY_create_by_OBJ` — X.501 relative distinguished name

# SYNOPSIS

library “libcrypto”
`#include <openssl/x509.h>`

X509_NAME_ENTRY *
`X509_NAME_ENTRY_new`(void);

void
`X509_NAME_ENTRY_free`(X509_NAME_ENTRY* ne);

ASN1_OBJECT *
`X509_NAME_ENTRY_get_object`(const X509_NAME_ENTRY *ne);

ASN1_STRING *
`X509_NAME_ENTRY_get_data`(const X509_NAME_ENTRY *ne);

int
`X509_NAME_ENTRY_set`(const X509_NAME_ENTRY *ne);

int
`X509_NAME_ENTRY_set_object`(X509_NAME_ENTRY *ne, const ASN1_OBJECT *obj);

int
`X509_NAME_ENTRY_set_data`(X509_NAME_ENTRY *ne, int type, const unsigned char *bytes, int len);

X509_NAME_ENTRY *
`X509_NAME_ENTRY_create_by_txt`(X509_NAME_ENTRY **ne, const char *field, int type, const unsigned char *bytes, int len);

X509_NAME_ENTRY *
`X509_NAME_ENTRY_create_by_NID`(X509_NAME_ENTRY **ne, int nid, int type, const unsigned char *bytes, int len);

X509_NAME_ENTRY *
`X509_NAME_ENTRY_create_by_OBJ`(X509_NAME_ENTRY **ne, const ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len);

# DESCRIPTION

An X.501 RelativeDistinguishedName is an ordered set of field type and value pairs. It is the building block for constructing X.501 Name objects. The X509_NAME_ENTRY object stores one such pair, containing one field type and one value.

X509_NAME_ENTRY objects are intended for use by the X509_NAME objects documented in X509_NAME_new(3). Since part of the information about how several X509_NAME_ENTRY objects combine to form an X.501 Name is stored in the individual X509_NAME_ENTRY objects rather than in the X509_NAME object, any given X509_NAME_ENTRY object can only be used by one X509_NAME object at a time.

`X509_NAME_ENTRY_new`() allocates and initializes an empty X509_NAME_ENTRY object, representing an ASN.1 RelativeDistinguishedName structure defined in RFC 5280 section 4.1.2.4, but containing not more than one type-value-pair.

`X509_NAME_ENTRY_free`() frees ne and the type and value contained in it.

`X509_NAME_ENTRY_get_object`() retrieves the field type of ne in an ASN1_OBJECT structure. `X509_NAME_ENTRY_get_data`() retrieves the field value of ne in an ASN1_STRING structure. These two functions can be used to examine an X509_NAME_ENTRY object as returned by X509_NAME_get_entry(3).

`X509_NAME_ENTRY_set`() retrieves the index of the X.501 RelativeDistinguishedName (RDN) that ne is part of in the X.501 Name object using it. The first RDN has index 0. If an RDN consists of more than one X509_NAME_ENTRY object, they all share the same index. In practice, RDNs containing more than one type-value-pair are rarely used, so if an X509_NAME *name object uses ne, then `X509_NAME_ENTRY_set`(ne) usually agrees with `sk_X509_NAME_ENTRY_find`(name->entries, ne), but when multi-pair RDNs are used, it may be smaller.

`X509_NAME_ENTRY_set_object`() sets the field type of ne to obj.

`X509_NAME_ENTRY_set_data`() sets the field value of ne to the given string type and the value determined by bytes and len. If the type argument is positive and includes the MBSTRING_FLAG bit, ASN1_STRING_set_by_NID(3) is used for setting the value, passing the type as the inform argument and using the nid corresponding to ne. Otherwise, if the type argument is `V_ASN1_APP_CHOOSE`, the type of ne is set to the return value of ASN1_PRINTABLE_type(3).

`X509_NAME_ENTRY_create_by_txt`(), `X509_NAME_ENTRY_create_by_NID`(), and `X509_NAME_ENTRY_create_by_OBJ`() create and return an X509_NAME_ENTRY structure.

Except for `X509_NAME_ENTRY_get_object`() and `X509_NAME_ENTRY_get_data`(), these functions are rarely used because X509_NAME_ENTRY structures are almost always part of X509_NAME structures and the functions described in X509_NAME_add_entry_by_txt(3) are typically used to create and add new entries in a single operation.

The arguments of these functions support similar options to the similarly named ones described in X509_NAME_add_entry_by_txt(3). So for example type can be set to `MBSTRING_ASC`, but in the case of `X509_NAME_ENTRY_set_data`() the field type must be set first so the relevant field information can be looked up internally.

# RETURN VALUES

The `X509_NAME_ENTRY_new`() function returns a valid X509_NAME_ENTRY structure if successful; otherwise `NULL` is returned and an error code can be retrieved with ERR_get_error(3).

`X509_NAME_ENTRY_get_object`() returns a valid ASN1_OBJECT structure if it is set or `NULL` if an error occurred.

`X509_NAME_ENTRY_get_data`() returns a valid ASN1_STRING structure if it is set or `NULL` if an error occurred.

`X509_NAME_ENTRY_set`() returns the zero-based index of the RDN ne is used in, or 0 if ne is not yet used by any X509_NAME object.

The `X509_NAME_ENTRY_set_object`() function returns 1 if successful; otherwise 0 is returned and an error code can be retrieved with ERR_get_error(3).

`X509_NAME_ENTRY_set_data`() returns 1 on success or 0 on error. In some cases of failure, the reason can be determined with ERR_get_error(3).

`X509_NAME_ENTRY_create_by_txt`(), `X509_NAME_ENTRY_create_by_NID`(), and `X509_NAME_ENTRY_create_by_OBJ`() return a valid X509_NAME_ENTRY structure on success or `NULL` if an error occurred. In some cases of failure, the reason can be determined with ERR_get_error(3).

# SEE ALSO

OBJ_nid2obj(3), X509_NAME_add_entry(3), X509_NAME_get_entry(3), X509_NAME_new(3)

# STANDARDS

RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile

ITU-T Recommendation X.501, also known as ISO/IEC 9594-2: Information Technology Open Systems Interconnection The Directory: Models, section 9.3: Relative distinguished name

# HISTORY

`X509_NAME_ENTRY_new`() and `X509_NAME_ENTRY_free`() first appeared in SSLeay 0.5.1. `X509_NAME_ENTRY_get_object`(), `X509_NAME_ENTRY_get_data`(), `X509_NAME_ENTRY_set_object`(), `X509_NAME_ENTRY_set_data`(), `X509_NAME_ENTRY_create_by_NID`(), and `X509_NAME_ENTRY_create_by_OBJ`() first appeared in SSLeay 0.8.0. These functions have been available since OpenBSD 2.4.

`X509_NAME_ENTRY_create_by_txt`() first appeared in OpenSSL 0.9.5 and has been available since OpenBSD 2.7.

`X509_NAME_ENTRY_set`() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 6.3.

# CAVEATS

Despite its name, `X509_NAME_ENTRY_set`() does not set anything. Something like “X509_NAME_ENTRY_get_set” would have been a better name.

June 8, 2025 | Debian