X509_NAME_get_index_by_NID 3 2008-05-09 0.9.9-dev OpenSSL

NAME

X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry, X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ - X509_NAME lookup and enumeration functions

LIBRARY

libcrypto, -lcrypto

SYNOPSIS


 #include 


 int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos);
 int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos);


 int X509_NAME_entry_count(X509_NAME *name);
 X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc);


 int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len);
 int X509_NAME_get_text_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len);

DESCRIPTION

These functions allow an XX550099__NNAAMMEE structure to be examined. The XX550099__NNAAMMEE structure is the same as the NNaammee type defined in RFC2459 (and elsewhere) and used for example in certificate subject and issuer names.

_X_5_0_9___N_A_M_E___g_e_t___i_n_d_e_x___b_y___N_I_D_(_) and _X_5_0_9___N_A_M_E___g_e_t___i_n_d_e_x___b_y___O_B_J_(_) retrieve the next index matching nniidd or oobbjj after llaassttppooss. llaassttppooss should initially be set to -1. If there are no more entries -1 is returned.

_X_5_0_9___N_A_M_E___e_n_t_r_y___c_o_u_n_t_(_) returns the total number of entries in nnaammee.

_X_5_0_9___N_A_M_E___g_e_t___e_n_t_r_y_(_) retrieves the XX550099__NNAAMMEE__EENNTTRRYY from nnaammee corresponding to index lloocc. Acceptable values for lloocc run from 0 to (X509_NAME_entry_count(name) - 1). The value returned is an internal pointer which must not be freed.

_X_5_0_9___N_A_M_E___g_e_t___t_e_x_t___b_y___N_I_D_(_), _X_5_0_9___N_A_M_E___g_e_t___t_e_x_t___b_y___O_B_J_(_) retrieve the "text" from the first entry in nnaammee which matches nniidd or oobbjj, if no such entry exists -1 is returned. At most lleenn bytes will be written and the text written to bbuuff will be null terminated. The length of the output string written is returned excluding the terminating null. If bbuuff is then the amount of space needed in bbuuff (excluding the final null) is returned.

NOTES

_X_5_0_9___N_A_M_E___g_e_t___t_e_x_t___b_y___N_I_D_(_) and _X_5_0_9___N_A_M_E___g_e_t___t_e_x_t___b_y___O_B_J_(_) are legacy functions which have various limitations which make them of minimal use in practice. They can only find the first matching entry and will copy the contents of the field verbatim: this can be highly confusing if the target is a muticharacter string type like a BMPString or a UTF8String.

For a more general solution _X_5_0_9___N_A_M_E___g_e_t___i_n_d_e_x___b_y___N_I_D_(_) or _X_5_0_9___N_A_M_E___g_e_t___i_n_d_e_x___b_y___O_B_J_(_) should be used followed by _X_5_0_9___N_A_M_E___g_e_t___e_n_t_r_y_(_) on any matching indices and then the various XX550099__NNAAMMEE__EENNTTRRYY utility functions on the result.

EXAMPLES

Process all entries:



 int i;
 X509_NAME_ENTRY *e;


 for (i = 0; i < X509_NAME_entry_count(nm); i++)
        {
        e = X509_NAME_get_entry(nm, i);
        /* Do something with e */
        }

Process all commonName entries:



 int loc;
 X509_NAME_ENTRY *e;








 loc = -1;
 for (;;)
        {
        lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos);
        if (lastpos == -1)
                break;
        e = X509_NAME_get_entry(nm, lastpos);
        /* Do something with e */
        }

RETURN VALUES

_X_5_0_9___N_A_M_E___g_e_t___i_n_d_e_x___b_y___N_I_D_(_) and _X_5_0_9___N_A_M_E___g_e_t___i_n_d_e_x___b_y___O_B_J_(_) return the index of the next matching entry or -1 if not found.

_X_5_0_9___N_A_M_E___e_n_t_r_y___c_o_u_n_t_(_) returns the total number of entries.

_X_5_0_9___N_A_M_E___g_e_t___e_n_t_r_y_(_) returns an XX550099__NNAAMMEE pointer to the requested entry or NNUULLLL if the index is invalid.

SEE ALSO

_E_R_R___g_e_t___e_r_r_o_r(3), _d_2_i___X_5_0_9___N_A_M_E(3)

HISTORY

TBA