]>
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 | |
aebb9aac | 13 | int X509_NAME_get_index_by_NID(X509_NAME *name, int nid, int lastpos); |
c47ba4e9 | 14 | int X509_NAME_get_index_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int lastpos); |
8c4b69d3 | 15 | |
333ed02c | 16 | int X509_NAME_entry_count(const X509_NAME *name); |
0fe91236 | 17 | X509_NAME_ENTRY *X509_NAME_get_entry(const X509_NAME *name, int loc); |
c264592d | 18 | |
aebb9aac | 19 | int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf, int len); |
c47ba4e9 | 20 | int X509_NAME_get_text_by_OBJ(X509_NAME *name, const 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 | |
1bc74519 | 47 | of space needed in B<buf> (excluding the final null) is returned. |
8c4b69d3 DSH |
48 | |
49 | =head1 NOTES | |
50 | ||
a95d7574 | 51 | X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() should be |
7f35627c | 52 | considered deprecated because they |
a95d7574 | 53 | have various limitations which make them |
8c4b69d3 DSH |
54 | of minimal use in practice. They can only find the first matching |
55 | entry and will copy the contents of the field verbatim: this can | |
186bb907 | 56 | be highly confusing if the target is a multicharacter string type |
8c4b69d3 DSH |
57 | like a BMPString or a UTF8String. |
58 | ||
59 | For a more general solution X509_NAME_get_index_by_NID() or | |
60 | X509_NAME_get_index_by_OBJ() should be used followed by | |
61 | X509_NAME_get_entry() on any matching indices and then the | |
62 | various B<X509_NAME_ENTRY> utility functions on the result. | |
63 | ||
64849586 MC |
64 | The list of all relevant B<NID_*> and B<OBJ_* codes> can be found in |
65 | the source code header files E<lt>openssl/obj_mac.hE<gt> and/or | |
66 | E<lt>openssl/objects.hE<gt>. | |
67 | ||
5727582c DSH |
68 | Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID() |
69 | should check for the return value of -2. Alternatively the NID validity | |
70 | can be determined first by checking OBJ_nid2obj(nid) is not NULL. | |
71 | ||
4564e77a PY |
72 | =head1 RETURN VALUES |
73 | ||
74 | X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() | |
75 | return the index of the next matching entry or -1 if not found. | |
76 | X509_NAME_get_index_by_NID() can also return -2 if the supplied | |
77 | NID is invalid. | |
78 | ||
79 | X509_NAME_entry_count() returns the total number of entries. | |
80 | ||
81 | X509_NAME_get_entry() returns an B<X509_NAME> pointer to the | |
82 | requested entry or B<NULL> if the index is invalid. | |
83 | ||
8c4b69d3 DSH |
84 | =head1 EXAMPLES |
85 | ||
86 | Process all entries: | |
87 | ||
88 | int i; | |
89 | X509_NAME_ENTRY *e; | |
90 | ||
2947af32 BB |
91 | for (i = 0; i < X509_NAME_entry_count(nm); i++) { |
92 | e = X509_NAME_get_entry(nm, i); | |
93 | /* Do something with e */ | |
94 | } | |
8c4b69d3 DSH |
95 | |
96 | Process all commonName entries: | |
97 | ||
5defbe6f | 98 | int lastpos = -1; |
8c4b69d3 DSH |
99 | X509_NAME_ENTRY *e; |
100 | ||
2947af32 BB |
101 | for (;;) { |
102 | lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); | |
103 | if (lastpos == -1) | |
104 | break; | |
105 | e = X509_NAME_get_entry(nm, lastpos); | |
106 | /* Do something with e */ | |
107 | } | |
8c4b69d3 | 108 | |
8c4b69d3 DSH |
109 | =head1 SEE ALSO |
110 | ||
9b86974e | 111 | L<ERR_get_error(3)>, L<d2i_X509_NAME(3)> |
8c4b69d3 | 112 | |
e2f92610 RS |
113 | =head1 COPYRIGHT |
114 | ||
83cf7abf | 115 | Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 116 | |
4746f25a | 117 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
118 | this file except in compliance with the License. You can obtain a copy |
119 | in the file LICENSE in the source distribution or at | |
120 | L<https://www.openssl.org/source/license.html>. | |
121 | ||
122 | =cut |