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:

tag	return value
V_ASN1_BIT_STRING	B_ASN1_BIT_STRING
V_ASN1_BMPSTRING	B_ASN1_BMPSTRING
V_ASN1_BOOLEAN	0
V_ASN1_ENUMERATED	B_ASN1_UNKNOWN
V_ASN1_EOC	0
V_ASN1_EXTERNAL	B_ASN1_UNKNOWN
V_ASN1_GENERALIZEDTIME	B_ASN1_GENERALIZEDTIME
V_ASN1_GENERALSTRING	B_ASN1_GENERALSTRING
V_ASN1_GRAPHICSTRING	B_ASN1_GRAPHICSTRING
V_ASN1_IA5STRING	B_ASN1_IA5STRING
V_ASN1_INTEGER	0
V_ASN1_ISO64STRING	B_ASN1_ISO64STRING
V_ASN1_NULL	0
V_ASN1_NUMERICSTRING	B_ASN1_NUMERICSTRING
V_ASN1_OBJECT	0
V_ASN1_OBJECT_DESCRIPTOR	B_ASN1_UNKNOWN
V_ASN1_OCTET_STRING	B_ASN1_OCTET_STRING
V_ASN1_PRINTABLESTRING	B_ASN1_PRINTABLESTRING
V_ASN1_REAL	B_ASN1_UNKNOWN
V_ASN1_SEQUENCE	B_ASN1_SEQUENCE
V_ASN1_SET	0
V_ASN1_T61STRING	B_ASN1_T61STRING
V_ASN1_TELETEXSTRING	B_ASN1_TELETEXSTRING
V_ASN1_UNDEF	0
V_ASN1_UNIVERSALSTRING	B_ASN1_UNIVERSALSTRING
V_ASN1_UTCTIME	B_ASN1_UTCTIME
V_ASN1_UTF8STRING	B_ASN1_UTF8STRING
V_ASN1_VIDEOTEXSTRING	B_ASN1_VIDEOTEXSTRING
V_ASN1_VISIBLESTRING	B_ASN1_VISIBLESTRING
11, 13, 14, 15, 29	B_ASN1_UNKNOWN
other (< 0, > 30)	0

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.