1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
.Dd $Mdocdate: November 4 2016 $
.Dt X509_NAME_GET_INDEX_BY_NID 3
.Os
.Sh NAME
.Nm X509_NAME_get_index_by_NID ,
.Nm X509_NAME_get_index_by_OBJ ,
.Nm X509_NAME_get_entry ,
.Nm X509_NAME_entry_count ,
.Nm X509_NAME_get_text_by_NID ,
.Nm X509_NAME_get_text_by_OBJ
.Nd X509_NAME lookup and enumeration functions
.Sh SYNOPSIS
.In openssl/x509.h
.Ft int
.Fo X509_NAME_get_index_by_NID
.Fa "X509_NAME *name"
.Fa "int nid"
.Fa "int lastpos"
.Fc
.Ft int
.Fo X509_NAME_get_index_by_OBJ
.Fa "X509_NAME *name"
.Fa "ASN1_OBJECT *obj"
.Fa "int lastpos"
.Fc
.Ft int
.Fo X509_NAME_entry_count
.Fa "X509_NAME *name"
.Fc
.Ft X509_NAME_ENTRY *
.Fo X509_NAME_get_entry
.Fa "X509_NAME *name"
.Fa "int loc"
.Fc
.Ft int
.Fo X509_NAME_get_text_by_NID
.Fa "X509_NAME *name"
.Fa "int nid"
.Fa "char *buf"
.Fa "int len"
.Fc
.Ft int
.Fo X509_NAME_get_text_by_OBJ
.Fa "X509_NAME *name"
.Fa "ASN1_OBJECT *obj"
.Fa "char *buf"
.Fa "int len"
.Fc
.Sh DESCRIPTION
These functions allow an
.Vt X509_NAME
structure to be examined.
The
.Vt X509_NAME
structure is the same as the
.Sy Name
type defined in RFC2459 (and elsewhere) and used for example in
certificate subject and issuer names.
.Pp
.Fn X509_NAME_get_index_by_NID
and
.Fn X509_NAME_get_index_by_OBJ
retrieve the next index matching
.Fa nid
or
.Fa obj
after
.Fa lastpos .
.Fa lastpos
should initially be set to -1.
If there are no more entries, -1 is returned.
.Pp
.Fn X509_NAME_entry_count
returns the total number of entries in
.Fa name .
.Pp
.Fn X509_NAME_get_entry
retrieves the
.Vt X509_NAME_ENTRY
from
.Fa name
corresponding to index
.Fa loc .
Acceptable values for
.Fa loc
run from 0 to
.Fn X509_NAME_entry_count name
- 1.
The value returned is an internal pointer which must not be freed.
.Pp
.Fn X509_NAME_get_text_by_NID
and
.Fn X509_NAME_get_text_by_OBJ
retrieve the "text" from the first entry in
.Fa name
which matches
.Fa nid
or
.Fa obj .
If no such entry exists, -1 is returned.
At most
.Fa len
bytes will be written and the text written to
.Fa buf
will be NUL terminated.
The length of the output string written is returned excluding the
terminating NUL.
If
.Fa buf
is
.Dv NULL
then the amount of space needed in
.Fa buf
(excluding the final NUL) is returned.
.Sh RETURN VALUES
.Fn X509_NAME_get_index_by_NID
and
.Fn X509_NAME_get_index_by_OBJ
return the index of the next matching entry or -1 if not found.
.Pp
.Fn X509_NAME_entry_count
returns the total number of entries.
.Pp
.Fn X509_NAME_get_entry
returns an
.Vt X509_NAME
pointer to the requested entry or
.Dv NULL
if the index is invalid.
.Sh EXAMPLES
Process all entries:
.Bd -literal
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 */
}
.Ed
.Pp
Process all commonName entries:
.Bd -literal
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 */
}
.Ed
.Sh SEE ALSO
.Xr d2i_X509_NAME 3 ,
.Xr ERR_get_error 3
.Sh CAVEATS
.Fn X509_NAME_get_text_by_NID
and
.Fn X509_NAME_get_text_by_OBJ
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
multicharacter string type like a BMPString or a UTF8String.
.Pp
For a more general solution,
.Fn X509_NAME_get_index_by_NID
or
.Fn X509_NAME_get_index_by_OBJ
should be used, followed by
.Fn X509_NAME_get_entry
on any matching indices and then the various
.Vt X509_NAME_ENTRY
utility functions on the result.
|
