]>
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. | |
32 | ||
33 | X509_NAME_entry_count() returns the total number of entries in B<name>. | |
34 | ||
35 | X509_NAME_get_entry() retrieves the B<X509_NAME_ENTRY> from B<name> | |
36 | corresponding to index B<loc>. Acceptable values for B<loc> run from | |
37 | 0 to (X509_NAME_entry_count(name) - 1). The value returned is an | |
38 | internal pointer which must not be freed. | |
39 | ||
40 | X509_NAME_get_text_by_NID(), X509_NAME_get_text_by_OBJ() retrieve | |
41 | the "text" from the first entry in B<name> which matches B<nid> or | |
42 | B<obj>, if no such entry exists -1 is returned. At most B<len> bytes | |
43 | will be written and the text written to B<buf> will be null | |
44 | terminated. The length of the output string written is returned | |
45 | excluding the terminating null. If B<buf> is <NULL> then the amount | |
46 | of space needed in B<buf> (excluding the final null) is returned. | |
47 | ||
48 | =head1 NOTES | |
49 | ||
50 | X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are | |
51 | legacy functions which have various limitations which make them | |
52 | of minimal use in practice. They can only find the first matching | |
53 | entry and will copy the contents of the field verbatim: this can | |
54 | be highly confusing if the target is a muticharacter string type | |
55 | like a BMPString or a UTF8String. | |
56 | ||
57 | For a more general solution X509_NAME_get_index_by_NID() or | |
58 | X509_NAME_get_index_by_OBJ() should be used followed by | |
59 | X509_NAME_get_entry() on any matching indices and then the | |
60 | various B<X509_NAME_ENTRY> utility functions on the result. | |
61 | ||
62 | =head1 EXAMPLES | |
63 | ||
64 | Process all entries: | |
65 | ||
66 | int i; | |
67 | X509_NAME_ENTRY *e; | |
68 | ||
69 | for (i = 0; i < X509_NAME_entry_count(nm); i++) | |
70 | { | |
71 | e = X509_NAME_get_entry(nm, i); | |
72 | /* Do something with e */ | |
73 | } | |
74 | ||
75 | Process all commonName entries: | |
76 | ||
77 | int loc; | |
78 | X509_NAME_ENTRY *e; | |
79 | ||
80 | loc = -1; | |
81 | for (;;) | |
82 | { | |
83 | lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); | |
84 | if (lastpos == -1) | |
85 | break; | |
86 | e = X509_NAME_get_entry(nm, lastpos); | |
87 | /* Do something with e */ | |
88 | } | |
89 | ||
90 | =head1 RETURN VALUES | |
91 | ||
92 | X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() | |
93 | return the index of the next matching entry or -1 if not found. | |
94 | ||
95 | X509_NAME_entry_count() returns the total number of entries. | |
96 | ||
97 | X509_NAME_get_entry() returns an B<X509_NAME> pointer to the | |
98 | requested entry or B<NULL> if the index is invalid. | |
99 | ||
100 | =head1 SEE ALSO | |
101 | ||
102 | L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)> | |
103 | ||
104 | =head1 HISTORY | |
105 | ||
106 | TBA | |
107 | ||
108 | =cut |