Debian Codegraph @

upstream/debian-unstable/man3/X509_NAME_get_index_by_NID.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "X509_NAME_GET_INDEX_BY_NID 3SSL"
58 .TH X509_NAME_GET_INDEX_BY_NID 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry,
65 X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ \-
66 X509_NAME lookup and enumeration functions
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/x509.h>
71 \&
72 \& int X509_NAME_get_index_by_NID(const X509_NAME *name, int nid, int lastpos);
73 \& int X509_NAME_get_index_by_OBJ(const X509_NAME *name,
74 \& const ASN1_OBJECT *obj, int lastpos);
75 \&
76 \& int X509_NAME_entry_count(const X509_NAME *name);
77 \& X509_NAME_ENTRY *X509_NAME_get_entry(const X509_NAME *name, int loc);
78 \&
79 \& int X509_NAME_get_text_by_NID(const X509_NAME *name, int nid,
80 \& char *buf, int len);
81 \& int X509_NAME_get_text_by_OBJ(const X509_NAME *name, const ASN1_OBJECT *obj,
82 \& char *buf, int len);
83 .Ve
84 .SH DESCRIPTION
85 .IX Header "DESCRIPTION"
86 These functions allow an \fBX509_NAME\fR structure to be examined. The
87 \&\fBX509_NAME\fR structure is the same as the \fBName\fR type defined in
88 RFC 5280 (and elsewhere) and used for example in certificate subject
89 and issuer names.
90 .PP
91 \&\fBX509_NAME_get_index_by_NID()\fR and \fBX509_NAME_get_index_by_OBJ()\fR retrieve
92 the next index matching \fBnid\fR or \fBobj\fR after \fBlastpos\fR. \fBlastpos\fR
93 should initially be set to \-1. If there are no more entries \-1 is returned.
94 If \fBnid\fR is invalid (doesn't correspond to a valid OID) then \-2 is returned.
95 .PP
96 \&\fBX509_NAME_entry_count()\fR returns the total number of entries in \fBname\fR.
97 .PP
98 \&\fBX509_NAME_get_entry()\fR retrieves the \fBX509_NAME_ENTRY\fR from \fBname\fR
99 corresponding to index \fBloc\fR. Acceptable values for \fBloc\fR run from
100 0 to (X509_NAME_entry_count(name) \- 1). The value returned is an
101 internal pointer which must not be freed.
102 .PP
103 \&\fBX509_NAME_get_text_by_NID()\fR, \fBX509_NAME_get_text_by_OBJ()\fR retrieve
104 the "text" from the first entry in \fBname\fR which matches \fBnid\fR or
105 \&\fBobj\fR, if no such entry exists \-1 is returned. At most \fBlen\fR bytes
106 will be written and the text written to \fBbuf\fR will be null
107 terminated. The length of the output string written is returned
108 excluding the terminating null. If \fBbuf\fR is <NULL> then the amount
109 of space needed in \fBbuf\fR (excluding the final null) is returned.
110 .SH NOTES
111 .IX Header "NOTES"
112 \&\fBX509_NAME_get_text_by_NID()\fR and \fBX509_NAME_get_text_by_OBJ()\fR should be
113 considered deprecated because they
114 have various limitations which make them
115 of minimal use in practice. They can only find the first matching
116 entry and will copy the contents of the field verbatim: this can
117 be highly confusing if the target is a multicharacter string type
118 like a BMPString or a UTF8String.
119 .PP
120 For a more general solution \fBX509_NAME_get_index_by_NID()\fR or
121 \&\fBX509_NAME_get_index_by_OBJ()\fR should be used followed by
122 \&\fBX509_NAME_get_entry()\fR on any matching indices and then the
123 various \fBX509_NAME_ENTRY\fR utility functions on the result.
124 .PP
125 The list of all relevant \fBNID_*\fR and \fBOBJ_* codes\fR can be found in
126 the source code header files \fI<openssl/obj_mac.h>\fR and/or
127 \&\fI<openssl/objects.h>\fR.
128 .PP
129 Applications which could pass invalid NIDs to \fBX509_NAME_get_index_by_NID()\fR
130 should check for the return value of \-2. Alternatively the NID validity
131 can be determined first by checking OBJ_nid2obj(nid) is not NULL.
132 .SH "RETURN VALUES"
133 .IX Header "RETURN VALUES"
134 \&\fBX509_NAME_get_index_by_NID()\fR and \fBX509_NAME_get_index_by_OBJ()\fR
135 return the index of the next matching entry or \-1 if not found.
136 \&\fBX509_NAME_get_index_by_NID()\fR can also return \-2 if the supplied
137 NID is invalid.
138 .PP
139 \&\fBX509_NAME_entry_count()\fR returns the total number of entries, and 0
140 for failure.
141 .PP
142 \&\fBX509_NAME_get_entry()\fR returns an \fBX509_NAME\fR pointer to the
143 requested entry or \fBNULL\fR if the index is invalid.
144 .SH EXAMPLES
145 .IX Header "EXAMPLES"
146 Process all entries:
147 .PP
148 .Vb 2
149 \& int i;
150 \& X509_NAME_ENTRY *e;
151 \&
152 \& for (i = 0; i < X509_NAME_entry_count(nm); i++) {
153 \& e = X509_NAME_get_entry(nm, i);
154 \& /* Do something with e */
155 \& }
156 .Ve
157 .PP
158 Process all commonName entries:
159 .PP
160 .Vb 2
161 \& int lastpos = \-1;
162 \& X509_NAME_ENTRY *e;
163 \&
164 \& for (;;) {
165 \& lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos);
166 \& if (lastpos == \-1)
167 \& break;
168 \& e = X509_NAME_get_entry(nm, lastpos);
169 \& /* Do something with e */
170 \& }
171 .Ve
172 .SH "SEE ALSO"
173 .IX Header "SEE ALSO"
174 \&\fBERR_get_error\fR\|(3), \fBd2i_X509_NAME\fR\|(3)
175 .SH COPYRIGHT
176 .IX Header "COPYRIGHT"
177 Copyright 2002\-2025 The OpenSSL Project Authors. All Rights Reserved.
178 .PP
179 Licensed under the Apache License 2.0 (the "License"). You may not use
180 this file except in compliance with the License. You can obtain a copy
181 in the file LICENSE in the source distribution or at
182 <https://www.openssl.org/source/license.html>.