NAME
ASN1_mbstring_copy
,
ASN1_mbstring_ncopy
,
ASN1_STRING_set_by_NID
,
ASN1_STRING_set_default_mask
,
ASN1_STRING_set_default_mask_asc
,
ASN1_STRING_get_default_mask
,
ASN1_tag2bit
—
copy a multibyte string into an ASN.1
string object
SYNOPSIS
#include
<openssl/asn1.h>
int
ASN1_mbstring_copy
(ASN1_STRING
**out, const unsigned char *in,
int inbytes, int inform,
unsigned long mask);
int
ASN1_mbstring_ncopy
(ASN1_STRING
**out, const unsigned char *in,
int inbytes, int inform,
unsigned long mask, long
minchars, long maxchars);
ASN1_STRING *
ASN1_STRING_set_by_NID
(ASN1_STRING
**out, const unsigned char *in,
int inbytes, int inform,
int nid);
void
ASN1_STRING_set_default_mask
(unsigned
long mask);
int
ASN1_STRING_set_default_mask_asc
(const
char *maskname);
unsigned long
ASN1_STRING_get_default_mask
(void);
unsigned long
ASN1_tag2bit
(int
tag);
DESCRIPTION
ASN1_mbstring_copy
()
interprets inbytes bytes starting at
in as a multibyte string and copies it to
*out, optionally changing the encoding. If the
inbytes argument is negative, the
strlen(3) of
in is used instead.
The inform argument specifies the character encoding of in:
inform | encoding |
MBSTRING_ASC |
ISO-Latin-1 |
MBSTRING_BMP |
UTF-16 |
MBSTRING_UNIV |
UTF-32 |
MBSTRING_UTF8 |
UTF-8 |
The bit mask specifies a set of ASN.1 string types that the user is willing to accept:
bit in mask | acceptable output type | default |
B_ASN1_PRINTABLESTRING |
ASN1_PRINTABLESTRING | yes |
B_ASN1_IA5STRING |
ASN1_IA5STRING | no |
B_ASN1_T61STRING |
ASN1_T61STRING | yes |
B_ASN1_BMPSTRING |
ASN1_BMPSTRING | yes |
B_ASN1_UNIVERSALSTRING |
ASN1_UNIVERSALSTRING | no |
any other bit | ASN1_UTF8STRING | yes |
The first type from the above table that is included in the mask argument and that can represent in is used as the output type. The “default” column indicates whether the type is considered acceptable if the mask argument has the special value 0.
The following bit mask constants each include several of the bits listed above:
mask constant | PRI | IA5 | T61 | BMP | UNI | UTF8 |
B_ASN1_DIRECTORYSTRING |
yes | no | yes | yes | yes | yes |
DIRSTRING_TYPE |
yes | no | yes | yes | no | yes |
PKCS9STRING_TYPE |
yes | yes | yes | yes | no | yes |
If out is NULL
,
inform, inbytes, and
in are validated and the output type is determined and
returned, but nothing is copied.
Otherwise, if *out is
NULL
, a new output object of the output type is
allocated and a pointer to it is stored in *out.
Otherwise, **out is used as the output object. Any data already stored in it is freed and its type is changed to the output type.
Finally, in is copied to the output object, changing the character encoding if inform does not match the encoding used by the output type.
ASN1_mbstring_ncopy
()
is similar except that the number of characters in in
is restricted to the range from minchars to
maxchars, inclusive. If maxchars
is 0, no upper limit is enforced on the number of characters.
ASN1_STRING_set_by_NID
()
is similar with the following differences:
- If out is
NULL
, a new output object is allocated and returned instead of skipping the copying. - If nid has a global string table entry that can be
retrieved with ASN1_STRING_TABLE_get(3), mask,
minchars, and maxchars are
taken from that string table entry. For some values of
nid, an additional global mask is AND'ed into the
mask before using it. The default value of the global mask is
B_ASN1_UTF8STRING
. - If nid has no global string
table entry,
B_ASN1_PRINTABLESTRING
|B_ASN1_T61STRING
|B_ASN1_BMPSTRING
|B_ASN1_UTF8STRING
is used instead of the mask taken from the table, and the global mask is also AND'ed into it. - Even though success and failure happen in the same situations, the return value is different. ASN1_STRING_type(3) can be used to determine the type of the return value.
ASN1_STRING_set_default_mask
()
sets the global mask used by
ASN1_STRING_set_by_NID
() to the
mask argument.
ASN1_STRING_set_default_mask_asc
()
sets the global mask as follows:
maskname | mask |
"default" | anything |
"nombstr" | anything except B_ASN1_BMPSTRING |
B_ASN1_UTF8STRING |
"pkix" | anything except B_ASN1_T61STRING |
"utf8only" | B_ASN1_UTF8STRING |
If the maskname argument starts with the substring "MASK:", the rest of it is interpreted as an unsigned long value using strtoul(3).
ASN1_tag2bit
()
translates ASN.1 data types to type bits as follows:
In typical usage, the calling code calculates the bitwise AND of the return value and a mask describing data types that the calling code is willing to use. If the result of the AND operation is non-zero, the data type is adequate; otherwise, the calling code may need to raise an error.
RETURN VALUES
ASN1_mbstring_copy
() and
ASN1_mbstring_ncopy
() return the
V_ASN1_*
constant representing the output type or -1
if inform is invalid, if inbytes
or in is invalid for the inform
encoding, if in contains an UTF-16 surrogate, which is
unsupported even for input using the UTF-16 encoding, or if memory
allocation fails.
ASN1_mbstring_ncopy
() also returns -1 if
in contains fewer than minchars
or more than maxchars characters.
ASN1_STRING_set_by_NID
() returns the new
or changed ASN.1 string object or NULL
on
failure.
ASN1_STRING_set_default_mask_asc
() returns
1 if successful or 0 if "MASK:" is not followed by a number, if
the number is followed by a non-numeric character, or if the
maskname is invalid.
ASN1_STRING_get_default_mask
() returns the
global mask.
ASN1_tag2bit
() returns a
B_ASN1_*
constant or 0.
SEE ALSO
ASN1_PRINTABLE_type(3), ASN1_STRING_new(3), ASN1_STRING_set(3), ASN1_STRING_TABLE_get(3), ASN1_UNIVERSALSTRING_to_string(3)
HISTORY
ASN1_mbstring_copy
(),
ASN1_mbstring_ncopy
(),
ASN1_STRING_set_by_NID
(),
ASN1_STRING_set_default_mask
(),
ASN1_STRING_set_default_mask_asc
(), and
ASN1_STRING_get_default_mask
() first appeared in
OpenSSL 0.9.5 and have been available since OpenBSD
2.7.
ASN1_tag2bit
() first appeared in OpenSSL
0.9.7 and has been available since OpenBSD 3.2.
BUGS
If integer overflow occurs in
ASN1_STRING_set_default_mask_asc
() while parsing a
number following "MASK:", the function succeeds, essentially
behaving in the same way as for "default".
Passing "default" to
ASN1_STRING_set_default_mask_asc
() does
not restore the
default mask. Instead, passing "utf8only" does that.