]>
Commit | Line | Data |
---|---|---|
8c4b69d3 DSH |
1 | =pod |
2 | ||
d479dc1d DSH |
3 | =head1 NAME |
4 | ||
8c4b69d3 DSH |
5 | X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry, |
6 | X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ - | |
7 | X509_NAME lookup and enumeration functions | |
8 | ||
8c4b69d3 DSH |
9 | =head1 SYNOPSIS |
10 | ||
c264592d | 11 | #include <openssl/x509.h> |
8c4b69d3 | 12 | |
c264592d UM |
13 | int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos); |
14 | int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos); | |
8c4b69d3 | 15 | |
c264592d UM |
16 | int X509_NAME_entry_count(X509_NAME *name); |
17 | X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc); | |
18 | ||
19 | int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len); | |
20 | int X509_NAME_get_text_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len); | |
8c4b69d3 DSH |
21 | |
22 | =head1 DESCRIPTION | |
23 | ||
24 | These functions allow an B<X509_NAME> structure to be examined. The | |
25 | B<X509_NAME> structure is the same as the B<Name> type defined in | |
26 | RFC2459 (and elsewhere) and used for example in certificate subject | |
27 | and issuer names. | |
28 | ||
29 | X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve | |
30 | the next index matching B<nid> or B<obj> after B<lastpos>. B<lastpos> | |
31 | should initially be set to -1. If there are no more entries -1 is returned. | |
5727582c | 32 | If B<nid> is invalid (doesn't correspond to a valid OID) then -2 is returned. |
8c4b69d3 DSH |
33 | |
34 | X509_NAME_entry_count() returns the total number of entries in B<name>. | |
35 | ||
36 | X509_NAME_get_entry() retrieves the B<X509_NAME_ENTRY> from B<name> | |
37 | corresponding to index B<loc>. Acceptable values for B<loc> run from | |
38 | 0 to (X509_NAME_entry_count(name) - 1). The value returned is an | |
39 | internal pointer which must not be freed. | |
40 | ||
41 | X509_NAME_get_text_by_NID(), X509_NAME_get_text_by_OBJ() retrieve | |
42 | the "text" from the first entry in B<name> which matches B<nid> or | |
43 | B<obj>, if no such entry exists -1 is returned. At most B<len> bytes | |
44 | will be written and the text written to B<buf> will be null | |
45 | terminated. The length of the output string written is returned | |
46 | excluding the terminating null. If B<buf> is <NULL> then the amount | |
47 | of space needed in B<buf> (excluding the final null) is returned. | |
48 | ||
49 | =head1 NOTES | |
50 | ||
51 | X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are | |
52 | legacy functions which have various limitations which make them | |
53 | of minimal use in practice. They can only find the first matching | |
54 | entry and will copy the contents of the field verbatim: this can | |
186bb907 | 55 | be highly confusing if the target is a multicharacter string type |
8c4b69d3 DSH |
56 | like a BMPString or a UTF8String. |
57 | ||
58 | For a more general solution X509_NAME_get_index_by_NID() or | |
59 | X509_NAME_get_index_by_OBJ() should be used followed by | |
60 | X509_NAME_get_entry() on any matching indices and then the | |
61 | various B<X509_NAME_ENTRY> utility functions on the result. | |
62 | ||
64849586 MC |
63 | The list of all relevant B<NID_*> and B<OBJ_* codes> can be found in |
64 | the source code header files E<lt>openssl/obj_mac.hE<gt> and/or | |
65 | E<lt>openssl/objects.hE<gt>. | |
66 | ||
5727582c DSH |
67 | Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID() |
68 | should check for the return value of -2. Alternatively the NID validity | |
69 | can be determined first by checking OBJ_nid2obj(nid) is not NULL. | |
70 | ||
8c4b69d3 DSH |
71 | =head1 EXAMPLES |
72 | ||
73 | Process all entries: | |
74 | ||
75 | int i; | |
76 | X509_NAME_ENTRY *e; | |
77 | ||
78 | for (i = 0; i < X509_NAME_entry_count(nm); i++) | |
79 | { | |
80 | e = X509_NAME_get_entry(nm, i); | |
81 | /* Do something with e */ | |
82 | } | |
83 | ||
84 | Process all commonName entries: | |
85 | ||
86 | int loc; | |
87 | X509_NAME_ENTRY *e; | |
88 | ||
89 | loc = -1; | |
90 | for (;;) | |
91 | { | |
92 | lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); | |
93 | if (lastpos == -1) | |
94 | break; | |
95 | e = X509_NAME_get_entry(nm, lastpos); | |
96 | /* Do something with e */ | |
97 | } | |
98 | ||
99 | =head1 RETURN VALUES | |
100 | ||
101 | X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() | |
102 | return the index of the next matching entry or -1 if not found. | |
5727582c DSH |
103 | X509_NAME_get_index_by_NID() can also return -2 if the supplied |
104 | NID is invalid. | |
8c4b69d3 DSH |
105 | |
106 | X509_NAME_entry_count() returns the total number of entries. | |
107 | ||
108 | X509_NAME_get_entry() returns an B<X509_NAME> pointer to the | |
109 | requested entry or B<NULL> if the index is invalid. | |
110 | ||
111 | =head1 SEE ALSO | |
112 | ||
9b86974e | 113 | L<ERR_get_error(3)>, L<d2i_X509_NAME(3)> |
8c4b69d3 DSH |
114 | |
115 | =head1 HISTORY | |
116 | ||
117 | TBA | |
118 | ||
119 | =cut |