X509_NAME_ENTRY Handling -- SSLeay 0.9.0b -- January 1999

NAME

X509_NAME_ENTRY_dup, X509_NAME_ENTRY_create_by_OBJ, X509_NAME_ENTRY_create_by_NID,
X509_NAME_ENTRY_get_object, X509_NAME_ENTRY_get_data, X509_NAME_ENTRY_set_object,
X509_NAME_ENTRY_set_data -- X509_NAME_ENTRY Handling

SYNOPSIS

#include "x509.h"

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

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

ASN1_OBJECT *X509_NAME_ENTRY_get_object(ne)
X509_NAME_ENTRY *ne;

ASN1_STRING *X509_NAME_ENTRY_get_data(ne)
X509_NAME_ENTRY *ne;

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

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

DESCRIPTION

If you haven't read through the ASN.1 documentation, you probably had better do so; this library relies heavily on that code.

Here's the ASN.1 for the Name subfield and its components:

Certificate Subfield 'Name' and its components

Name            ::=   CHOICE { -- only one possibility for now --
                                 rdnSequence  RDNSequence }

RDNSequence     ::=   SEQUENCE OF RelativeDistinguishedName

DistinguishedName       ::=   RDNSequence

RelativeDistinguishedName  ::=
                    SET SIZE (1 .. MAX) OF AttributeTypeAndValue

AttributeTypeAndValue           ::=     SEQUENCE {
        type    AttributeType,
        value   AttributeValue }

AttributeType           ::=   OBJECT IDENTIFIER

AttributeValue          ::=   ANY

Now let's look at X509_NAME_ENTRY as the library defines it:

typedef struct X509_name_entry_st
        {
        ASN1_OBJECT *object;
        ASN1_STRING *value;
        int set;
        int size;       /* temp variable */
        } X509_NAME_ENTRY;

The generic routines for new, free, and i2d/d2i conversion for X509_NAME are discussed in X.509 Certificate Substructures; the functions specific to X509_NAME only are described here.

X509_NAME_ENTRY_dup is actually a macro:

#define X509_NAME_ENTRY_dup(ne) 
  (X509_NAME_ENTRY *)ASN1_dup((int (*)())i2d_X509_NAME_ENTRY, 
  (char *(*)())d2i_X509_NAME_ENTRY,(char *)ne)

It makes a copy of the X509_NAME structure that ne points to and returns it, or NULL on error.

X509_NAME_ENTRY_create_by_OBJ fills in *ne, using obj to fill in the object subfield, and bytes, len and type to fill in the data subfield.

If ne or *ne is NULL, a new X509_NAME_ENTRY structure will be created. If ne is not NULL, then *ne will be set to point to the new structure.

A pointer to the newly populated structure is returned, or NULL on error.

X509_NAME_ENTRY_create_by_NID does the same thing as X509_NAME_ENTRY_create_by_OBJ, except that you pass a nid instead of an obj, and the function calls OBJ_nid2obj to get an object from the nid.

X509_NAME_ENTRY_get_object returns a pointer to the object subfield of ne.

X509_NAME_ENTRY_get_data returns a pointer to the value subfield of ne. This is an ASN1_STRING.

X509_NAME_ENTRY_set_object frees the object subfield of ne if needed, makes a copy of obj, and sets the object subfield of ne to point to the copy. It returns 1 on success and 0 on error.

X509_NAME_ENTRY_set_data sets the value subfield of ne with bytes, where len is the length of bytes. If type is V_ASN1_APP_CHOOSE then the type of value (an ASN1_STRING) will be set to the smallest characterset type (using ASN1_PRINTABLE_type() to determine this) that includes the characters in bytes. Otherwise, it will be set to type. The function returns 1 on success and 0 on error.