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