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