1109998Smarkm=pod 2109998Smarkm 3109998Smarkm=head1 NAME 4109998Smarkm 5109998SmarkmX509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry, 6109998SmarkmX509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ - 7109998SmarkmX509_NAME lookup and enumeration functions 8109998Smarkm 9109998Smarkm=head1 SYNOPSIS 10109998Smarkm 11215697Ssimon #include <openssl/x509.h> 12109998Smarkm 13215697Ssimon int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos); 14215697Ssimon int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos); 15109998Smarkm 16215697Ssimon int X509_NAME_entry_count(X509_NAME *name); 17215697Ssimon X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc); 18109998Smarkm 19215697Ssimon int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len); 20215697Ssimon int X509_NAME_get_text_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len); 21215697Ssimon 22109998Smarkm=head1 DESCRIPTION 23109998Smarkm 24109998SmarkmThese functions allow an B<X509_NAME> structure to be examined. The 25109998SmarkmB<X509_NAME> structure is the same as the B<Name> type defined in 26109998SmarkmRFC2459 (and elsewhere) and used for example in certificate subject 27109998Smarkmand issuer names. 28109998Smarkm 29109998SmarkmX509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve 30109998Smarkmthe next index matching B<nid> or B<obj> after B<lastpos>. B<lastpos> 31109998Smarkmshould initially be set to -1. If there are no more entries -1 is returned. 32285330SjkimIf B<nid> is invalid (doesn't correspond to a valid OID) then -2 is returned. 33109998Smarkm 34109998SmarkmX509_NAME_entry_count() returns the total number of entries in B<name>. 35109998Smarkm 36109998SmarkmX509_NAME_get_entry() retrieves the B<X509_NAME_ENTRY> from B<name> 37109998Smarkmcorresponding to index B<loc>. Acceptable values for B<loc> run from 38109998Smarkm0 to (X509_NAME_entry_count(name) - 1). The value returned is an 39109998Smarkminternal pointer which must not be freed. 40109998Smarkm 41109998SmarkmX509_NAME_get_text_by_NID(), X509_NAME_get_text_by_OBJ() retrieve 42109998Smarkmthe "text" from the first entry in B<name> which matches B<nid> or 43109998SmarkmB<obj>, if no such entry exists -1 is returned. At most B<len> bytes 44109998Smarkmwill be written and the text written to B<buf> will be null 45109998Smarkmterminated. The length of the output string written is returned 46109998Smarkmexcluding the terminating null. If B<buf> is <NULL> then the amount 47109998Smarkmof space needed in B<buf> (excluding the final null) is returned. 48109998Smarkm 49109998Smarkm=head1 NOTES 50109998Smarkm 51109998SmarkmX509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are 52109998Smarkmlegacy functions which have various limitations which make them 53109998Smarkmof minimal use in practice. They can only find the first matching 54109998Smarkmentry and will copy the contents of the field verbatim: this can 55109998Smarkmbe highly confusing if the target is a muticharacter string type 56109998Smarkmlike a BMPString or a UTF8String. 57109998Smarkm 58109998SmarkmFor a more general solution X509_NAME_get_index_by_NID() or 59109998SmarkmX509_NAME_get_index_by_OBJ() should be used followed by 60109998SmarkmX509_NAME_get_entry() on any matching indices and then the 61109998Smarkmvarious B<X509_NAME_ENTRY> utility functions on the result. 62109998Smarkm 63276864SjkimThe list of all relevant B<NID_*> and B<OBJ_* codes> can be found in 64276864Sjkimthe source code header files E<lt>openssl/obj_mac.hE<gt> and/or 65276864SjkimE<lt>openssl/objects.hE<gt>. 66276864Sjkim 67285330SjkimApplications which could pass invalid NIDs to X509_NAME_get_index_by_NID() 68285330Sjkimshould check for the return value of -2. Alternatively the NID validity 69285330Sjkimcan be determined first by checking OBJ_nid2obj(nid) is not NULL. 70285330Sjkim 71109998Smarkm=head1 EXAMPLES 72109998Smarkm 73109998SmarkmProcess all entries: 74109998Smarkm 75109998Smarkm int i; 76109998Smarkm X509_NAME_ENTRY *e; 77109998Smarkm 78109998Smarkm for (i = 0; i < X509_NAME_entry_count(nm); i++) 79109998Smarkm { 80109998Smarkm e = X509_NAME_get_entry(nm, i); 81109998Smarkm /* Do something with e */ 82109998Smarkm } 83109998Smarkm 84109998SmarkmProcess all commonName entries: 85109998Smarkm 86109998Smarkm int loc; 87109998Smarkm X509_NAME_ENTRY *e; 88109998Smarkm 89109998Smarkm loc = -1; 90109998Smarkm for (;;) 91109998Smarkm { 92109998Smarkm lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); 93109998Smarkm if (lastpos == -1) 94109998Smarkm break; 95109998Smarkm e = X509_NAME_get_entry(nm, lastpos); 96109998Smarkm /* Do something with e */ 97109998Smarkm } 98109998Smarkm 99109998Smarkm=head1 RETURN VALUES 100109998Smarkm 101109998SmarkmX509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() 102109998Smarkmreturn the index of the next matching entry or -1 if not found. 103285330SjkimX509_NAME_get_index_by_NID() can also return -2 if the supplied 104285330SjkimNID is invalid. 105109998Smarkm 106109998SmarkmX509_NAME_entry_count() returns the total number of entries. 107109998Smarkm 108109998SmarkmX509_NAME_get_entry() returns an B<X509_NAME> pointer to the 109109998Smarkmrequested entry or B<NULL> if the index is invalid. 110109998Smarkm 111109998Smarkm=head1 SEE ALSO 112109998Smarkm 113109998SmarkmL<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)> 114109998Smarkm 115109998Smarkm=head1 HISTORY 116109998Smarkm 117109998SmarkmTBA 118109998Smarkm 119109998Smarkm=cut 120