1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
.\" $OpenBSD: ASN1_mbstring_copy.3,v 1.1 2021/10/20 13:14:00 schwarze Exp $
.\"
.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: October 20 2021 $
.Dt ASN1_MBSTRING_COPY 3
.Os
.Sh NAME
.Nm ASN1_mbstring_copy ,
.Nm ASN1_mbstring_ncopy
.Nd copy a mutibyte string into an ASN.1 string object
.Sh SYNOPSIS
.In openssl/asn1.h
.Ft int
.Fo ASN1_mbstring_copy
.Fa "ASN1_STRING **out"
.Fa "const unsigned char *in"
.Fa "int inbytes"
.Fa "int inform"
.Fa "unsigned long mask"
.Fc
.Ft int
.Fo ASN1_mbstring_ncopy
.Fa "ASN1_STRING **out"
.Fa "const unsigned char *in"
.Fa "int inbytes"
.Fa "int inform"
.Fa "unsigned long mask"
.Fa "long minchars"
.Fa "long maxchars"
.Fc
.Sh DESCRIPTION
.Fn ASN1_mbstring_copy
interprets
.Fa inbytes
bytes starting at
.Fa in
as a multibyte string and copies it to
.Pf * Fa out ,
optionally changing the encoding.
If the
.Fa inbytes
argument is negative, the
.Xr strlen 3
of
.Fa in
is used instead.
.Pp
The
.Fa inform
argument specifies the character encoding of
.Fa in :
.Bl -column MBSTRING_UNIV encoding
.It Ar inform Ta encoding
.It Dv MBSTRING_ASC Ta ISO-Latin-1
.It Dv MBSTRING_BMP Ta UTF-16
.It Dv MBSTRING_UNIV Ta UTF-32
.It Dv MBSTRING_UTF8 Ta UTF-8
.El
.Pp
The bit
.Fa mask
specifies a set of ASN.1 string types
that the user is willing to accept:
.Bl -column B_ASN1_UNIVERSALSTRING ASN1_UNIVERSALSTRING default
.It bit in Fa mask Ta acceptable output type Ta default
.It Dv B_ASN1_PRINTABLESTRING Ta Vt ASN1_PRINTABLESTRING Ta yes
.It Dv B_ASN1_IA5STRING Ta Vt ASN1_IA5STRING Ta no
.It Dv B_ASN1_T61STRING Ta Vt ASN1_T61STRING Ta yes
.It Dv B_ASN1_BMPSTRING Ta Vt ASN1_BMPSTRING Ta yes
.It Dv B_ASN1_UNIVERSALSTRING Ta Vt ASN1_UNIVERSALSTRING Ta no
.It any other bit Ta Vt ASN1_UTF8STRING Ta yes
.El
.Pp
The first type from the above table that is included in the
.Fa mask
argument and that can represent
.Fa in
is used as the output type.
The
.Dq default
column indicates whether the type is considered acceptable if the
.Fa mask
argument has the special value 0.
.Pp
If
.Fa out
is
.Dv NULL ,
.Fa inform ,
.Fa inbytes ,
and
.Fa in
are validated and the output type is determined and returned,
but nothing is copied.
.Pp
Otherwise, if
.Pf * Fa out
is
.Dv NULL ,
a new output object of the output type is allocated
and a pointer to it is stored in
.Pf * Fa out .
.Pp
Otherwise,
.Pf ** Fa out
is used as the output object.
Any data already stored in it is freed
and its type is changed to the output type.
.Pp
Finally,
.Fa in
is copied to the output object, changing the character encoding if
.Fa inform
does not match the encoding used by the output type.
.Pp
.Fn ASN1_mbstring_ncopy
is similar except that the number of characters in
.Fa in
is restricted to the range from
.Fa minchars
to
.Fa maxchars ,
inclusive.
If
.Fa maxchars
is 0, no upper limit is enforced on the number of characters.
.Sh RETURN VALUES
.Fn ASN1_mbstring_copy
and
.Fn ASN1_mbstring_ncopy
return the
.Dv V_ASN1_*
constant representing the output type or \-1 if
.Fa inform
is invalid, if
.Fa inbytes
or
.Fa in
is invalid for the
.Fa inform
encoding, if
.Fa in
contains an UTF-16 surrogate,
which is unsupported even for input using the UTF-16 encoding,
or if memory allocation fails.
.Pp
.Fn ASN1_mbstring_ncopy
also returns \-1 if
.Fa in
contains fewer than
.Fa minchars
or more than
.Fa maxchars
characters.
.Sh SEE ALSO
.Xr ASN1_STRING_new 3 ,
.Xr ASN1_STRING_set 3
.Sh HISTORY
These functions first appeared in OpenSSL 0.9.5
and have been available since
.Ox 2.7 .
|
