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