| blob | b03bc3f10cd75e96040ee807291f8ec70ce511f3 |
1 .\" $NetBSD: OBJ_nid2obj.3,v 1.14 2015/06/12 17:01:14 christos Exp $
2 .\"
3 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
4 .\"
5 .\" Standard preamble:
6 .\" ========================================================================
7 .de Sp \" Vertical space (when we can't use .PP)
8 .if t .sp .5v
9 .if n .sp
10 ..
11 .de Vb \" Begin verbatim text
12 .ft CW
13 .nf
14 .ne \\$1
15 ..
16 .de Ve \" End verbatim text
17 .ft R
18 .fi
19 ..
20 .\" Set up some character translations and predefined strings. \*(-- will
21 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
22 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
23 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
24 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
25 .\" nothing in troff, for use with C<>.
26 .tr \(*W-
27 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
28 .ie n \{\
29 . ds -- \(*W-
30 . ds PI pi
31 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
32 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
33 . ds L" ""
34 . ds R" ""
35 . ds C` ""
36 . ds C' ""
37 'br\}
38 .el\{\
39 . ds -- \|\(em\|
40 . ds PI \(*p
41 . ds L" ``
42 . ds R" ''
43 . ds C`
44 . ds C'
45 'br\}
46 .\"
47 .\" Escape single quotes in literal strings from groff's Unicode transform.
48 .ie \n(.g .ds Aq \(aq
49 .el .ds Aq '
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .\"
56 .\" Avoid warning from groff about undefined register 'F'.
57 .de IX
58 ..
59 .nr rF 0
60 .if \n(.g .if rF .nr rF 1
61 .if (\n(rF:(\n(.g==0)) \{
62 . if \nF \{
63 . de IX
64 . tm Index:\\$1\t\\n%\t"\\$2"
65 ..
66 . if !\nF==2 \{
67 . nr % 0
68 . nr F 2
69 . \}
70 . \}
71 .\}
72 .rr rF
73 .\"
74 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
75 .\" Fear. Run. Save yourself. No user-serviceable parts.
76 . \" fudge factors for nroff and troff
77 .if n \{\
78 . ds #H 0
79 . ds #V .8m
80 . ds #F .3m
81 . ds #[ \f1
82 . ds #] \fP
83 .\}
84 .if t \{\
85 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
86 . ds #V .6m
87 . ds #F 0
88 . ds #[ \&
89 . ds #] \&
90 .\}
91 . \" simple accents for nroff and troff
92 .if n \{\
93 . ds ' \&
94 . ds ` \&
95 . ds ^ \&
96 . ds , \&
97 . ds ~ ~
98 . ds /
99 .\}
100 .if t \{\
101 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
102 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
103 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
104 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
105 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
106 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
107 .\}
108 . \" troff and (daisy-wheel) nroff accents
109 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
110 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
111 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
112 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
113 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
114 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
115 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
116 .ds ae a\h'-(\w'a'u*4/10)'e
117 .ds Ae A\h'-(\w'A'u*4/10)'E
118 . \" corrections for vroff
119 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
120 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
121 . \" for low resolution devices (crt and lpr)
122 .if \n(.H>23 .if \n(.V>19 \
123 \{\
124 . ds : e
125 . ds 8 ss
126 . ds o a
127 . ds d- d\h'-1'\(ga
128 . ds D- D\h'-1'\(hy
129 . ds th \o'bp'
130 . ds Th \o'LP'
131 . ds ae ae
132 . ds Ae AE
133 .\}
134 .rm #[ #] #H #V #F C
135 .\" ========================================================================
136 .\"
137 .IX Title "OBJ_nid2obj 3"
138 .TH OBJ_nid2obj 3 "2009-07-19" "1.0.1n" "OpenSSL"
139 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
140 .\" way too many mistakes in technical documents.
141 .if n .ad l
142 .nh
143 .SH "NAME"
144 OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid,
145 OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup \- ASN1 object utility
146 functions
147 .SH "LIBRARY"
148 libcrypto, -lcrypto
149 .SH "SYNOPSIS"
150 .IX Header "SYNOPSIS"
151 .Vb 1
152 \& #include <openssl/objects.h>
153 \&
154 \& ASN1_OBJECT * OBJ_nid2obj(int n);
155 \& const char * OBJ_nid2ln(int n);
156 \& const char * OBJ_nid2sn(int n);
157 \&
158 \& int OBJ_obj2nid(const ASN1_OBJECT *o);
159 \& int OBJ_ln2nid(const char *ln);
160 \& int OBJ_sn2nid(const char *sn);
161 \&
162 \& int OBJ_txt2nid(const char *s);
163 \&
164 \& ASN1_OBJECT * OBJ_txt2obj(const char *s, int no_name);
165 \& int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name);
166 \&
167 \& int OBJ_cmp(const ASN1_OBJECT *a,const ASN1_OBJECT *b);
168 \& ASN1_OBJECT * OBJ_dup(const ASN1_OBJECT *o);
169 \&
170 \& int OBJ_create(const char *oid,const char *sn,const char *ln);
171 \& void OBJ_cleanup(void);
172 .Ve
173 .SH "DESCRIPTION"
174 .IX Header "DESCRIPTION"
175 The \s-1ASN1\s0 object utility functions process \s-1ASN1_OBJECT\s0 structures which are
176 a representation of the \s-1ASN1 OBJECT IDENTIFIER \s0(\s-1OID\s0) type.
177 .PP
178 \&\fIOBJ_nid2obj()\fR, \fIOBJ_nid2ln()\fR and \fIOBJ_nid2sn()\fR convert the \s-1NID \s0\fBn\fR to
179 an \s-1ASN1_OBJECT\s0 structure, its long name and its short name respectively,
180 or \fB\s-1NULL\s0\fR is an error occurred.
181 .PP
182 \&\fIOBJ_obj2nid()\fR, \fIOBJ_ln2nid()\fR, \fIOBJ_sn2nid()\fR return the corresponding \s-1NID\s0
183 for the object \fBo\fR, the long name <ln> or the short name <sn> respectively
184 or NID_undef if an error occurred.
185 .PP
186 \&\fIOBJ_txt2nid()\fR returns \s-1NID\s0 corresponding to text string <s>. \fBs\fR can be
187 a long name, a short name or the numerical respresentation of an object.
188 .PP
189 \&\fIOBJ_txt2obj()\fR converts the text string \fBs\fR into an \s-1ASN1_OBJECT\s0 structure.
190 If \fBno_name\fR is 0 then long names and short names will be interpreted
191 as well as numerical forms. If \fBno_name\fR is 1 only the numerical form
192 is acceptable.
193 .PP
194 \&\fIOBJ_obj2txt()\fR converts the \fB\s-1ASN1_OBJECT\s0\fR \fBa\fR into a textual representation.
195 The representation is written as a null terminated string to \fBbuf\fR
196 at most \fBbuf_len\fR bytes are written, truncating the result if necessary.
197 The total amount of space required is returned. If \fBno_name\fR is 0 then
198 if the object has a long or short name then that will be used, otherwise
199 the numerical form will be used. If \fBno_name\fR is 1 then the numerical
200 form will always be used.
201 .PP
202 \&\fIOBJ_cmp()\fR compares \fBa\fR to \fBb\fR. If the two are identical 0 is returned.
203 .PP
204 \&\fIOBJ_dup()\fR returns a copy of \fBo\fR.
205 .PP
206 \&\fIOBJ_create()\fR adds a new object to the internal table. \fBoid\fR is the
207 numerical form of the object, \fBsn\fR the short name and \fBln\fR the
208 long name. A new \s-1NID\s0 is returned for the created object.
209 .PP
210 \&\fIOBJ_cleanup()\fR cleans up OpenSSLs internal object table: this should
211 be called before an application exits if any new objects were added
212 using \fIOBJ_create()\fR.
213 .SH "NOTES"
214 .IX Header "NOTES"
215 Objects in OpenSSL can have a short name, a long name and a numerical
216 identifier (\s-1NID\s0) associated with them. A standard set of objects is
217 represented in an internal table. The appropriate values are defined
218 in the header file \fBobjects.h\fR.
219 .PP
220 For example the \s-1OID\s0 for commonName has the following definitions:
221 .PP
222 .Vb 3
223 \& #define SN_commonName "CN"
224 \& #define LN_commonName "commonName"
225 \& #define NID_commonName 13
226 .Ve
227 .PP
228 New objects can be added by calling \fIOBJ_create()\fR.
229 .PP
230 Table objects have certain advantages over other objects: for example
231 their NIDs can be used in a C language switch statement. They are
232 also static constant structures which are shared: that is there
233 is only a single constant structure for each table object.
234 .PP
235 Objects which are not in the table have the \s-1NID\s0 value NID_undef.
236 .PP
237 Objects do not need to be in the internal tables to be processed,
238 the functions \fIOBJ_txt2obj()\fR and \fIOBJ_obj2txt()\fR can process the numerical
239 form of an \s-1OID.\s0
240 .SH "EXAMPLES"
241 .IX Header "EXAMPLES"
242 Create an object for \fBcommonName\fR:
243 .PP
244 .Vb 2
245 \& ASN1_OBJECT *o;
246 \& o = OBJ_nid2obj(NID_commonName);
247 .Ve
248 .PP
249 Check if an object is \fBcommonName\fR
250 .PP
251 .Vb 2
252 \& if (OBJ_obj2nid(obj) == NID_commonName)
253 \& /* Do something */
254 .Ve
255 .PP
256 Create a new \s-1NID\s0 and initialize an object from it:
257 .PP
258 .Vb 3
259 \& int new_nid;
260 \& ASN1_OBJECT *obj;
261 \& new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
262 \&
263 \& obj = OBJ_nid2obj(new_nid);
264 .Ve
265 .PP
266 Create a new object directly:
267 .PP
268 .Vb 1
269 \& obj = OBJ_txt2obj("1.2.3.4", 1);
270 .Ve
271 .SH "BUGS"
272 .IX Header "BUGS"
273 \&\fIOBJ_obj2txt()\fR is awkward and messy to use: it doesn't follow the
274 convention of other OpenSSL functions where the buffer can be set
275 to \fB\s-1NULL\s0\fR to determine the amount of data that should be written.
276 Instead \fBbuf\fR must point to a valid buffer and \fBbuf_len\fR should
277 be set to a positive value. A buffer length of 80 should be more
278 than enough to handle any \s-1OID\s0 encountered in practice.
279 .SH "RETURN VALUES"
280 .IX Header "RETURN VALUES"
281 \&\fIOBJ_nid2obj()\fR returns an \fB\s-1ASN1_OBJECT\s0\fR structure or \fB\s-1NULL\s0\fR is an
282 error occurred.
283 .PP
284 \&\fIOBJ_nid2ln()\fR and \fIOBJ_nid2sn()\fR returns a valid string or \fB\s-1NULL\s0\fR
285 on error.
286 .PP
287 \&\fIOBJ_obj2nid()\fR, \fIOBJ_ln2nid()\fR, \fIOBJ_sn2nid()\fR and \fIOBJ_txt2nid()\fR return
288 a \s-1NID\s0 or \fBNID_undef\fR on error.
289 .SH "SEE ALSO"
290 .IX Header "SEE ALSO"
291 \&\fIERR_get_error\fR\|(3)
292 .SH "HISTORY"
293 .IX Header "HISTORY"
294 \&\s-1TBA\s0