xref: /openbsd-src/lib/libcrypto/man/ASN1_mbstring_copy.3 (revision 4e1ee0786f11cc571bd0be17d38e46f635c719fc) 
1.\" $OpenBSD: ASN1_mbstring_copy.3,v 1.2 2021/10/20 15:54:21 schwarze Exp $
2.\"
3.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: October 20 2021 $
18.Dt ASN1_MBSTRING_COPY 3
19.Os
20.Sh NAME
21.Nm ASN1_mbstring_copy ,
22.Nm ASN1_mbstring_ncopy ,
23.Nm ASN1_STRING_set_by_NID ,
24.Nm ASN1_STRING_set_default_mask ,
25.Nm ASN1_STRING_set_default_mask_asc ,
26.Nm ASN1_STRING_get_default_mask
27.Nd copy a mutibyte string into an ASN.1 string object
28.Sh SYNOPSIS
29.In openssl/asn1.h
30.Ft int
31.Fo ASN1_mbstring_copy
32.Fa "ASN1_STRING **out"
33.Fa "const unsigned char *in"
34.Fa "int inbytes"
35.Fa "int inform"
36.Fa "unsigned long mask"
37.Fc
38.Ft int
39.Fo ASN1_mbstring_ncopy
40.Fa "ASN1_STRING **out"
41.Fa "const unsigned char *in"
42.Fa "int inbytes"
43.Fa "int inform"
44.Fa "unsigned long mask"
45.Fa "long minchars"
46.Fa "long maxchars"
47.Fc
48.Ft ASN1_STRING *
49.Fo ASN1_STRING_set_by_NID
50.Fa "ASN1_STRING **out"
51.Fa "const unsigned char *in"
52.Fa "int inbytes"
53.Fa "int inform"
54.Fa "int nid"
55.Fc
56.Ft void
57.Fo ASN1_STRING_set_default_mask
58.Fa "unsigned long mask"
59.Fc
60.Ft int
61.Fo ASN1_STRING_set_default_mask_asc
62.Fa "const char *maskname"
63.Fc
64.Ft unsigned long
65.Fn ASN1_STRING_get_default_mask void
66.Sh DESCRIPTION
67.Fn ASN1_mbstring_copy
68interprets
69.Fa inbytes
70bytes starting at
71.Fa in
72as a multibyte string and copies it to
73.Pf * Fa out ,
74optionally changing the encoding.
75If the
76.Fa inbytes
77argument is negative, the
78.Xr strlen 3
79of
80.Fa in
81is used instead.
82.Pp
83The
84.Fa inform
85argument specifies the character encoding of
86.Fa in :
87.Bl -column MBSTRING_UNIV encoding
88.It Ar inform Ta encoding
89.It Dv MBSTRING_ASC Ta ISO-Latin-1
90.It Dv MBSTRING_BMP Ta UTF-16
91.It Dv MBSTRING_UNIV Ta UTF-32
92.It Dv MBSTRING_UTF8 Ta UTF-8
93.El
94.Pp
95The bit
96.Fa mask
97specifies a set of ASN.1 string types
98that the user is willing to accept:
99.Bl -column B_ASN1_UNIVERSALSTRING ASN1_UNIVERSALSTRING default
100.It bit in Fa mask            Ta acceptable output type  Ta default
101.It Dv B_ASN1_PRINTABLESTRING Ta Vt ASN1_PRINTABLESTRING Ta yes
102.It Dv B_ASN1_IA5STRING       Ta Vt ASN1_IA5STRING       Ta no
103.It Dv B_ASN1_T61STRING       Ta Vt ASN1_T61STRING       Ta yes
104.It Dv B_ASN1_BMPSTRING       Ta Vt ASN1_BMPSTRING       Ta yes
105.It Dv B_ASN1_UNIVERSALSTRING Ta Vt ASN1_UNIVERSALSTRING Ta no
106.It any other bit             Ta Vt ASN1_UTF8STRING      Ta yes
107.El
108.Pp
109The first type from the above table that is included in the
110.Fa mask
111argument and that can represent
112.Fa in
113is used as the output type.
114The
115.Dq default
116column indicates whether the type is considered acceptable if the
117.Fa mask
118argument has the special value 0.
119.Pp
120If
121.Fa out
122is
123.Dv NULL ,
124.Fa inform ,
125.Fa inbytes ,
126and
127.Fa in
128are validated and the output type is determined and returned,
129but nothing is copied.
130.Pp
131Otherwise, if
132.Pf * Fa out
133is
134.Dv NULL ,
135a new output object of the output type is allocated
136and a pointer to it is stored in
137.Pf * Fa out .
138.Pp
139Otherwise,
140.Pf ** Fa out
141is used as the output object.
142Any data already stored in it is freed
143and its type is changed to the output type.
144.Pp
145Finally,
146.Fa in
147is copied to the output object, changing the character encoding if
148.Fa inform
149does not match the encoding used by the output type.
150.Pp
151.Fn ASN1_mbstring_ncopy
152is similar except that the number of characters in
153.Fa in
154is restricted to the range from
155.Fa minchars
156to
157.Fa maxchars ,
158inclusive.
159If
160.Fa maxchars
161is 0, no upper limit is enforced on the number of characters.
162.Pp
163.Fn ASN1_STRING_set_by_NID
164is similar with the following differences:
165.Bl -bullet -width 1n
166.It
167If
168.Fa out
169is
170.Dv NULL ,
171a new output object is allocated and returned
172instead of skipping the copying.
173.It
174If
175.Fa nid
176has a global string table entry that can be retrieved with
177.Xr ASN1_STRING_TABLE_get 3 ,
178.Fa mask ,
179.Fa minchars ,
180and
181.Fa maxchars
182are taken from that string table entry.
183For some values of
184.Fa nid ,
185an additional global mask is AND'ed into the mask before using it.
186The default value of the global mask is
187.Dv B_ASN1_UTF8STRING .
188.It
189If
190.Fa nid
191has no global string table entry,
192.Dv B_ASN1_PRINTABLESTRING | B_ASN1_T61STRING |
193.Dv B_ASN1_BMPSTRING | B_ASN1_UTF8STRING
194is used instead of the mask taken from the table,
195and the global mask is also AND'ed into it.
196.It
197Even though success and failure happen in the same situations,
198the return value is different.
199.Xr ASN1_STRING_type 3
200can be used to determine the type of the return value.
201.El
202.Pp
203.Fn ASN1_STRING_set_default_mask
204sets the global mask used by
205.Fn ASN1_STRING_set_by_NID
206to the
207.Fa mask
208argument.
209.Pp
210.Fn ASN1_STRING_set_default_mask_asc
211sets the global mask as follows:
212.Bl -column utf8only
213.It Ar maskname    Ta Ar mask
214.It Qo default  Qc Ta anything
215.It Qo nombstr  Qc Ta anything except Dv B_ASN1_BMPSTRING | B_ASN1_UTF8STRING
216.It Qo pkix     Qc Ta anything except Dv B_ASN1_T61STRING
217.It Qo utf8only Qc Ta Dv B_ASN1_UTF8STRING
218.El
219.Pp
220If the
221.Fa maskname
222argument starts with the substring
223.Qq MASK:\& ,
224the rest of it is interpreted as an
225.Vt unsigned long
226value using
227.Xr strtoul 3 .
228.Sh RETURN VALUES
229.Fn ASN1_mbstring_copy
230and
231.Fn ASN1_mbstring_ncopy
232return the
233.Dv V_ASN1_*
234constant representing the output type or \-1 if
235.Fa inform
236is invalid, if
237.Fa inbytes
238or
239.Fa in
240is invalid for the
241.Fa inform
242encoding, if
243.Fa in
244contains an UTF-16 surrogate,
245which is unsupported even for input using the UTF-16 encoding,
246or if memory allocation fails.
247.Pp
248.Fn ASN1_mbstring_ncopy
249also returns \-1 if
250.Fa in
251contains fewer than
252.Fa minchars
253or more than
254.Fa maxchars
255characters.
256.Pp
257.Fn ASN1_STRING_set_by_NID
258returns the new or changed ASN.1 string object or
259.Dv NULL
260on failure.
261.Pp
262.Fn ASN1_STRING_set_default_mask_asc
263returns 1 if successful or 0 if
264.Qq MASK:\&
265is not followed by a number, if the number is followed by a non-numeric
266character, or if the
267.Fa maskname
268is invalid.
269.Pp
270.Fn ASN1_STRING_get_default_mask
271returns the global mask.
272.Sh SEE ALSO
273.Xr ASN1_STRING_new 3 ,
274.Xr ASN1_STRING_set 3 ,
275.Xr ASN1_STRING_TABLE_get 3
276.Sh HISTORY
277These functions first appeared in OpenSSL 0.9.5
278and have been available since
279.Ox 2.7 .
280.Sh BUGS
281If integer overflow occurs in
282.Fn ASN1_STRING_set_default_mask_asc
283while parsing a number following
284.Qq MASK:\& ,
285the function succeeds, essentially behaving in the same way as for
286.Qq default .
287.Pp
288Passing
289.Qq default
290to
291.Fn ASN1_STRING_set_default_mask_asc
292does
293.Em not
294restore the default mask.
295Instead, passing
296.Qq utf8only
297does that.
298