Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / OBJ_nid2obj.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH OBJ_nid2obj 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid,
74dab6c2 192OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup \- ASN1 object utility
984263bc
MD
193functions
194.SH "SYNOPSIS"
74dab6c2 195.PP
984263bc
MD
196.Vb 3
197\& ASN1_OBJECT * OBJ_nid2obj(int n);
198\& const char * OBJ_nid2ln(int n);
199\& const char * OBJ_nid2sn(int n);
200.Ve
201.Vb 3
202\& int OBJ_obj2nid(const ASN1_OBJECT *o);
203\& int OBJ_ln2nid(const char *ln);
204\& int OBJ_sn2nid(const char *sn);
205.Ve
206.Vb 1
207\& int OBJ_txt2nid(const char *s);
208.Ve
209.Vb 2
210\& ASN1_OBJECT * OBJ_txt2obj(const char *s, int no_name);
211\& int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name);
212.Ve
213.Vb 2
214\& int OBJ_cmp(const ASN1_OBJECT *a,const ASN1_OBJECT *b);
215\& ASN1_OBJECT * OBJ_dup(const ASN1_OBJECT *o);
216.Ve
217.Vb 2
218\& int OBJ_create(const char *oid,const char *sn,const char *ln);
219\& void OBJ_cleanup(void);
220.Ve
221.SH "DESCRIPTION"
74dab6c2
JR
222The ASN1 object utility functions process ASN1_OBJECT structures which are
223a representation of the ASN1 OBJECT IDENTIFIER (OID) type.
984263bc 224.PP
74dab6c2
JR
225\fIOBJ_nid2obj()\fR, \fIOBJ_nid2ln()\fR and \fIOBJ_nid2sn()\fR convert the NID \fBn\fR to
226an ASN1_OBJECT structure, its long name and its short name respectively,
227or \fBNULL\fR is an error occurred.
984263bc 228.PP
74dab6c2 229\fIOBJ_obj2nid()\fR, \fIOBJ_ln2nid()\fR, \fIOBJ_sn2nid()\fR return the corresponding NID
984263bc
MD
230for the object \fBo\fR, the long name <ln> or the short name <sn> respectively
231or NID_undef if an error occurred.
232.PP
74dab6c2 233\fIOBJ_txt2nid()\fR returns NID corresponding to text string <s>. \fBs\fR can be
984263bc
MD
234a long name, a short name or the numerical respresentation of an object.
235.PP
74dab6c2 236\fIOBJ_txt2obj()\fR converts the text string \fBs\fR into an ASN1_OBJECT structure.
984263bc
MD
237If \fBno_name\fR is 0 then long names and short names will be interpreted
238as well as numerical forms. If \fBno_name\fR is 1 only the numerical form
239is acceptable.
240.PP
74dab6c2 241\fIOBJ_obj2txt()\fR converts the \fBASN1_OBJECT\fR \fBa\fR into a textual representation.
984263bc
MD
242The representation is written as a null terminated string to \fBbuf\fR
243at most \fBbuf_len\fR bytes are written, truncating the result if necessary.
244The total amount of space required is returned. If \fBno_name\fR is 0 then
245if the object has a long or short name then that will be used, otherwise
246the numerical form will be used. If \fBno_name\fR is 1 then the numerical
247form will always be used.
248.PP
74dab6c2 249\fIOBJ_cmp()\fR compares \fBa\fR to \fBb\fR. If the two are identical 0 is returned.
984263bc 250.PP
74dab6c2 251\fIOBJ_dup()\fR returns a copy of \fBo\fR.
984263bc 252.PP
74dab6c2 253\fIOBJ_create()\fR adds a new object to the internal table. \fBoid\fR is the
984263bc 254numerical form of the object, \fBsn\fR the short name and \fBln\fR the
74dab6c2 255long name. A new NID is returned for the created object.
984263bc 256.PP
74dab6c2 257\fIOBJ_cleanup()\fR cleans up OpenSSLs internal object table: this should
984263bc
MD
258be called before an application exits if any new objects were added
259using \fIOBJ_create()\fR.
260.SH "NOTES"
984263bc 261Objects in OpenSSL can have a short name, a long name and a numerical
74dab6c2 262identifier (NID) associated with them. A standard set of objects is
984263bc
MD
263represented in an internal table. The appropriate values are defined
264in the header file \fBobjects.h\fR.
265.PP
74dab6c2 266For example the OID for commonName has the following definitions:
984263bc
MD
267.PP
268.Vb 3
269\& #define SN_commonName "CN"
270\& #define LN_commonName "commonName"
271\& #define NID_commonName 13
272.Ve
273New objects can be added by calling \fIOBJ_create()\fR.
274.PP
275Table objects have certain advantages over other objects: for example
276their NIDs can be used in a C language switch statement. They are
277also static constant structures which are shared: that is there
278is only a single constant structure for each table object.
279.PP
74dab6c2 280Objects which are not in the table have the NID value NID_undef.
984263bc
MD
281.PP
282Objects do not need to be in the internal tables to be processed,
283the functions \fIOBJ_txt2obj()\fR and \fIOBJ_obj2txt()\fR can process the numerical
74dab6c2 284form of an OID.
984263bc 285.SH "EXAMPLES"
984263bc
MD
286Create an object for \fBcommonName\fR:
287.PP
288.Vb 2
289\& ASN1_OBJECT *o;
290\& o = OBJ_nid2obj(NID_commonName);
291.Ve
292Check if an object is \fBcommonName\fR
293.PP
294.Vb 2
295\& if (OBJ_obj2nid(obj) == NID_commonName)
296\& /* Do something */
297.Ve
74dab6c2 298Create a new NID and initialize an object from it:
984263bc
MD
299.PP
300.Vb 3
301\& int new_nid;
302\& ASN1_OBJECT *obj;
303\& new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
304.Ve
74dab6c2 305.Vb 3
984263bc 306\& obj = OBJ_nid2obj(new_nid);
74dab6c2
JR
307\&
308\&Create a new object directly:
984263bc 309.Ve
984263bc
MD
310.Vb 1
311\& obj = OBJ_txt2obj("1.2.3.4", 1);
312.Ve
313.SH "BUGS"
74dab6c2 314\fIOBJ_obj2txt()\fR is awkward and messy to use: it doesn't follow the
984263bc 315convention of other OpenSSL functions where the buffer can be set
74dab6c2 316to \fBNULL\fR to determine the amount of data that should be written.
984263bc
MD
317Instead \fBbuf\fR must point to a valid buffer and \fBbuf_len\fR should
318be set to a positive value. A buffer length of 80 should be more
74dab6c2 319than enough to handle any OID encountered in practice.
984263bc 320.SH "RETURN VALUES"
74dab6c2 321\fIOBJ_nid2obj()\fR returns an \fBASN1_OBJECT\fR structure or \fBNULL\fR is an
984263bc
MD
322error occurred.
323.PP
74dab6c2 324\fIOBJ_nid2ln()\fR and \fIOBJ_nid2sn()\fR returns a valid string or \fBNULL\fR
984263bc
MD
325on error.
326.PP
74dab6c2
JR
327\fIOBJ_obj2nid()\fR, \fIOBJ_ln2nid()\fR, \fIOBJ_sn2nid()\fR and \fIOBJ_txt2nid()\fR return
328a NID or \fBNID_undef\fR on error.
984263bc 329.SH "SEE ALSO"
984263bc
MD
330ERR_get_error(3)
331.SH "HISTORY"
74dab6c2
JR
332TBA
333
334.rn }` ''
335.IX Title "OBJ_nid2obj 3"
336.IX Name "OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid,
337OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup - ASN1 object utility
338functions"
339
340.IX Header "NAME"
341
342.IX Header "SYNOPSIS"
343
344.IX Header "DESCRIPTION"
345
346.IX Header "NOTES"
347
348.IX Header "EXAMPLES"
349
350.IX Header "BUGS"
351
352.IX Header "RETURN VALUES"
353
354.IX Header "SEE ALSO"
355
984263bc 356.IX Header "HISTORY"
74dab6c2 357