---
name: "libressl-ASN1_mbstring_copy"
section: "3"
platform: "linux"
package: "libressl"
version: "4.4.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libressl-ASN1_mbstring_copy"
---

# libressl-ASN1\_mbstring\_copy(3)

copy a multibyte string into an ASN.1 string object

## 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

Crypto Library (libcrypto, -lcrypto)

**#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)](/strlen/3.md) 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)](/strtoul/3.md).

**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.