summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/ASN1_mbstring_copy.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/ASN1_mbstring_copy.3')
-rw-r--r--src/lib/libcrypto/man/ASN1_mbstring_copy.3369
1 files changed, 0 insertions, 369 deletions
diff --git a/src/lib/libcrypto/man/ASN1_mbstring_copy.3 b/src/lib/libcrypto/man/ASN1_mbstring_copy.3
deleted file mode 100644
index e0b48aaa62..0000000000
--- a/src/lib/libcrypto/man/ASN1_mbstring_copy.3
+++ /dev/null
@@ -1,369 +0,0 @@
1.\" $OpenBSD: ASN1_mbstring_copy.3,v 1.6 2022/02/21 00:22:03 jsg 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: February 21 2022 $
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.Nm ASN1_tag2bit
28.Nd copy a multibyte string into an ASN.1 string object
29.Sh SYNOPSIS
30.In openssl/asn1.h
31.Ft int
32.Fo ASN1_mbstring_copy
33.Fa "ASN1_STRING **out"
34.Fa "const unsigned char *in"
35.Fa "int inbytes"
36.Fa "int inform"
37.Fa "unsigned long mask"
38.Fc
39.Ft int
40.Fo ASN1_mbstring_ncopy
41.Fa "ASN1_STRING **out"
42.Fa "const unsigned char *in"
43.Fa "int inbytes"
44.Fa "int inform"
45.Fa "unsigned long mask"
46.Fa "long minchars"
47.Fa "long maxchars"
48.Fc
49.Ft ASN1_STRING *
50.Fo ASN1_STRING_set_by_NID
51.Fa "ASN1_STRING **out"
52.Fa "const unsigned char *in"
53.Fa "int inbytes"
54.Fa "int inform"
55.Fa "int nid"
56.Fc
57.Ft void
58.Fo ASN1_STRING_set_default_mask
59.Fa "unsigned long mask"
60.Fc
61.Ft int
62.Fo ASN1_STRING_set_default_mask_asc
63.Fa "const char *maskname"
64.Fc
65.Ft unsigned long
66.Fn ASN1_STRING_get_default_mask void
67.Ft unsigned long
68.Fn ASN1_tag2bit "int tag"
69.Sh DESCRIPTION
70.Fn ASN1_mbstring_copy
71interprets
72.Fa inbytes
73bytes starting at
74.Fa in
75as a multibyte string and copies it to
76.Pf * Fa out ,
77optionally changing the encoding.
78If the
79.Fa inbytes
80argument is negative, the
81.Xr strlen 3
82of
83.Fa in
84is used instead.
85.Pp
86The
87.Fa inform
88argument specifies the character encoding of
89.Fa in :
90.Bl -column MBSTRING_UNIV encoding
91.It Ar inform Ta encoding
92.It Dv MBSTRING_ASC Ta ISO-Latin-1
93.It Dv MBSTRING_BMP Ta UTF-16
94.It Dv MBSTRING_UNIV Ta UTF-32
95.It Dv MBSTRING_UTF8 Ta UTF-8
96.El
97.Pp
98The bit
99.Fa mask
100specifies a set of ASN.1 string types
101that the user is willing to accept:
102.Bl -column B_ASN1_UNIVERSALSTRING ASN1_UNIVERSALSTRING default
103.It bit in Fa mask Ta acceptable output type Ta default
104.It Dv B_ASN1_PRINTABLESTRING Ta Vt ASN1_PRINTABLESTRING Ta yes
105.It Dv B_ASN1_IA5STRING Ta Vt ASN1_IA5STRING Ta no
106.It Dv B_ASN1_T61STRING Ta Vt ASN1_T61STRING Ta yes
107.It Dv B_ASN1_BMPSTRING Ta Vt ASN1_BMPSTRING Ta yes
108.It Dv B_ASN1_UNIVERSALSTRING Ta Vt ASN1_UNIVERSALSTRING Ta no
109.It any other bit Ta Vt ASN1_UTF8STRING Ta yes
110.El
111.Pp
112The first type from the above table that is included in the
113.Fa mask
114argument and that can represent
115.Fa in
116is used as the output type.
117The
118.Dq default
119column indicates whether the type is considered acceptable if the
120.Fa mask
121argument has the special value 0.
122.Pp
123The following bit mask constants
124each include several of the bits listed above:
125.Bl -column B_ASN1_DIRECTORYSTRING_ MMM MMM MMM MMM MMM MMMM
126.It mask constant Ta PRI Ta IA5 Ta T61 Ta BMP Ta UNI Ta UTF8
127.It Dv B_ASN1_DIRECTORYSTRING Ta yes Ta no Ta yes Ta yes Ta yes Ta yes
128.It Dv DIRSTRING_TYPE Ta yes Ta no Ta yes Ta yes Ta no Ta yes
129.It Dv PKCS9STRING_TYPE Ta yes Ta yes Ta yes Ta yes Ta no Ta yes
130.El
131.Pp
132If
133.Fa out
134is
135.Dv NULL ,
136.Fa inform ,
137.Fa inbytes ,
138and
139.Fa in
140are validated and the output type is determined and returned,
141but nothing is copied.
142.Pp
143Otherwise, if
144.Pf * Fa out
145is
146.Dv NULL ,
147a new output object of the output type is allocated
148and a pointer to it is stored in
149.Pf * Fa out .
150.Pp
151Otherwise,
152.Pf ** Fa out
153is used as the output object.
154Any data already stored in it is freed
155and its type is changed to the output type.
156.Pp
157Finally,
158.Fa in
159is copied to the output object, changing the character encoding if
160.Fa inform
161does not match the encoding used by the output type.
162.Pp
163.Fn ASN1_mbstring_ncopy
164is similar except that the number of characters in
165.Fa in
166is restricted to the range from
167.Fa minchars
168to
169.Fa maxchars ,
170inclusive.
171If
172.Fa maxchars
173is 0, no upper limit is enforced on the number of characters.
174.Pp
175.Fn ASN1_STRING_set_by_NID
176is similar with the following differences:
177.Bl -bullet -width 1n
178.It
179If
180.Fa out
181is
182.Dv NULL ,
183a new output object is allocated and returned
184instead of skipping the copying.
185.It
186If
187.Fa nid
188has a global string table entry that can be retrieved with
189.Xr ASN1_STRING_TABLE_get 3 ,
190.Fa mask ,
191.Fa minchars ,
192and
193.Fa maxchars
194are taken from that string table entry.
195For some values of
196.Fa nid ,
197an additional global mask is AND'ed into the mask before using it.
198The default value of the global mask is
199.Dv B_ASN1_UTF8STRING .
200.It
201If
202.Fa nid
203has no global string table entry,
204.Dv B_ASN1_PRINTABLESTRING | B_ASN1_T61STRING |
205.Dv B_ASN1_BMPSTRING | B_ASN1_UTF8STRING
206is used instead of the mask taken from the table,
207and the global mask is also AND'ed into it.
208.It
209Even though success and failure happen in the same situations,
210the return value is different.
211.Xr ASN1_STRING_type 3
212can be used to determine the type of the return value.
213.El
214.Pp
215.Fn ASN1_STRING_set_default_mask
216sets the global mask used by
217.Fn ASN1_STRING_set_by_NID
218to the
219.Fa mask
220argument.
221.Pp
222.Fn ASN1_STRING_set_default_mask_asc
223sets the global mask as follows:
224.Bl -column utf8only
225.It Ar maskname Ta Ar mask
226.It Qo default Qc Ta anything
227.It Qo nombstr Qc Ta anything except Dv B_ASN1_BMPSTRING | B_ASN1_UTF8STRING
228.It Qo pkix Qc Ta anything except Dv B_ASN1_T61STRING
229.It Qo utf8only Qc Ta Dv B_ASN1_UTF8STRING
230.El
231.Pp
232If the
233.Fa maskname
234argument starts with the substring
235.Qq MASK:\& ,
236the rest of it is interpreted as an
237.Vt unsigned long
238value using
239.Xr strtoul 3 .
240.Pp
241.Fn ASN1_tag2bit
242translates ASN.1 data types to type bits as follows:
243.Bl -column V_ASN1_OBJECT_DESCRIPTOR B_ASN1_UNIVERSALSTRING
244.It Fa tag Ta return value
245.It Dv V_ASN1_BIT_STRING Ta Dv B_ASN1_BIT_STRING
246.It Dv V_ASN1_BMPSTRING Ta Dv B_ASN1_BMPSTRING
247.It Dv V_ASN1_BOOLEAN Ta 0
248.It Dv V_ASN1_ENUMERATED Ta Dv B_ASN1_UNKNOWN
249.It Dv V_ASN1_EOC Ta 0
250.It Dv V_ASN1_EXTERNAL Ta Dv B_ASN1_UNKNOWN
251.It Dv V_ASN1_GENERALIZEDTIME Ta Dv B_ASN1_GENERALIZEDTIME
252.It Dv V_ASN1_GENERALSTRING Ta Dv B_ASN1_GENERALSTRING
253.It Dv V_ASN1_GRAPHICSTRING Ta Dv B_ASN1_GRAPHICSTRING
254.It Dv V_ASN1_IA5STRING Ta Dv B_ASN1_IA5STRING
255.It Dv V_ASN1_INTEGER Ta 0
256.It Dv V_ASN1_ISO64STRING Ta Dv B_ASN1_ISO64STRING
257.It Dv V_ASN1_NULL Ta 0
258.It Dv V_ASN1_NUMERICSTRING Ta Dv B_ASN1_NUMERICSTRING
259.It Dv V_ASN1_OBJECT Ta 0
260.It Dv V_ASN1_OBJECT_DESCRIPTOR Ta Dv B_ASN1_UNKNOWN
261.It Dv V_ASN1_OCTET_STRING Ta Dv B_ASN1_OCTET_STRING
262.It Dv V_ASN1_PRINTABLESTRING Ta Dv B_ASN1_PRINTABLESTRING
263.It Dv V_ASN1_REAL Ta Dv B_ASN1_UNKNOWN
264.It Dv V_ASN1_SEQUENCE Ta Dv B_ASN1_SEQUENCE
265.It Dv V_ASN1_SET Ta 0
266.It Dv V_ASN1_T61STRING Ta Dv B_ASN1_T61STRING
267.It Dv V_ASN1_TELETEXSTRING Ta Dv B_ASN1_TELETEXSTRING
268.It Dv V_ASN1_UNDEF Ta 0
269.It Dv V_ASN1_UNIVERSALSTRING Ta Dv B_ASN1_UNIVERSALSTRING
270.It Dv V_ASN1_UTCTIME Ta Dv B_ASN1_UTCTIME
271.It Dv V_ASN1_UTF8STRING Ta Dv B_ASN1_UTF8STRING
272.It Dv V_ASN1_VIDEOTEXSTRING Ta Dv B_ASN1_VIDEOTEXSTRING
273.It Dv V_ASN1_VISIBLESTRING Ta Dv B_ASN1_VISIBLESTRING
274.It 11, 13, 14, 15, 29 Ta Dv B_ASN1_UNKNOWN
275.It Dv other Po < 0, > 30 Pc Ta Dv 0
276.El
277.Pp
278In typical usage, the calling code calculates the bitwise AND
279of the return value and a mask describing data types
280that the calling code is willing to use.
281If the result of the AND operation is non-zero, the data type is
282adequate; otherwise, the calling code may need to raise an error.
283.Sh RETURN VALUES
284.Fn ASN1_mbstring_copy
285and
286.Fn ASN1_mbstring_ncopy
287return the
288.Dv V_ASN1_*
289constant representing the output type or \-1 if
290.Fa inform
291is invalid, if
292.Fa inbytes
293or
294.Fa in
295is invalid for the
296.Fa inform
297encoding, if
298.Fa in
299contains an UTF-16 surrogate,
300which is unsupported even for input using the UTF-16 encoding,
301or if memory allocation fails.
302.Pp
303.Fn ASN1_mbstring_ncopy
304also returns \-1 if
305.Fa in
306contains fewer than
307.Fa minchars
308or more than
309.Fa maxchars
310characters.
311.Pp
312.Fn ASN1_STRING_set_by_NID
313returns the new or changed ASN.1 string object or
314.Dv NULL
315on failure.
316.Pp
317.Fn ASN1_STRING_set_default_mask_asc
318returns 1 if successful or 0 if
319.Qq MASK:\&
320is not followed by a number, if the number is followed by a non-numeric
321character, or if the
322.Fa maskname
323is invalid.
324.Pp
325.Fn ASN1_STRING_get_default_mask
326returns the global mask.
327.Pp
328.Fn ASN1_tag2bit
329returns a
330.Dv B_ASN1_*
331constant or 0.
332.Sh SEE ALSO
333.Xr ASN1_PRINTABLE_type 3 ,
334.Xr ASN1_STRING_new 3 ,
335.Xr ASN1_STRING_set 3 ,
336.Xr ASN1_STRING_TABLE_get 3 ,
337.Xr ASN1_UNIVERSALSTRING_to_string 3
338.Sh HISTORY
339.Fn ASN1_mbstring_copy ,
340.Fn ASN1_mbstring_ncopy ,
341.Fn ASN1_STRING_set_by_NID ,
342.Fn ASN1_STRING_set_default_mask ,
343.Fn ASN1_STRING_set_default_mask_asc ,
344and
345.Fn ASN1_STRING_get_default_mask
346first appeared in OpenSSL 0.9.5 and have been available since
347.Ox 2.7 .
348.Pp
349.Fn ASN1_tag2bit
350first appeared in OpenSSL 0.9.7 and has been available since
351.Ox 3.2 .
352.Sh BUGS
353If integer overflow occurs in
354.Fn ASN1_STRING_set_default_mask_asc
355while parsing a number following
356.Qq MASK:\& ,
357the function succeeds, essentially behaving in the same way as for
358.Qq default .
359.Pp
360Passing
361.Qq default
362to
363.Fn ASN1_STRING_set_default_mask_asc
364does
365.Em not
366restore the default mask.
367Instead, passing
368.Qq utf8only
369does that.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 15:56:35 +0000