ASN1_MBSTRING_COPY(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

💅 ASN1_MBSTRING_COPY(3) 💅

okay so this is from the Library Functions Manual bestie, and it's literally all about copying a multibyte string into an ASN.1 string object. seven whole functions, one page, let's go 🫶

✨ 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 — the whole squad whose job is to copy a multibyte string into an ASN.1 string object. that's the vibe. 🦋

🌸 SYNOPSIS 🌸

library libcrypto

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

so ASN1_mbstring_copy() takes inbytes bytes starting at in, treats them as a multibyte string, and copies the whole thing to *out — optionally swapping the encoding while it's at it. and if inbytes is negative? no worries babe, it just falls back to the strlen(3) of in instead. iconic behaviour honestly.

the inform argument is literally "hey what encoding is in in", and here's the tea:

  • MBSTRING_ASC — ISO-Latin-1
  • MBSTRING_BMP — UTF-16
  • MBSTRING_UNIV — UTF-32
  • MBSTRING_UTF8 — UTF-8

then the bit mask is like, the set of ASN.1 string types you're willing to accept as output. here's the chart bestie:

  • B_ASN1_PRINTABLESTRING — gives you ASN1_PRINTABLESTRING — default: yes
  • B_ASN1_IA5STRING — gives you ASN1_IA5STRING — default: no
  • B_ASN1_T61STRING — gives you ASN1_T61STRING — default: yes
  • B_ASN1_BMPSTRING — gives you ASN1_BMPSTRING — default: yes
  • B_ASN1_UNIVERSALSTRING — gives you ASN1_UNIVERSALSTRING — default: no
  • any other bit — gives you ASN1_UTF8STRING — default: yes

the way it works: the first type from that table that's included in the mask argument and can actually represent in is the one that wins and becomes your output type. and that "default" column? that's just telling you whether the type counts as acceptable when mask has the special value 0. cute right 💖

also these bit mask constants each bundle up several of the bits above, so you don't have to spell them out:

  • B_ASN1_DIRECTORYSTRING — PRI yes, IA5 no, T61 yes, BMP yes, UNI yes, UTF8 yes
  • DIRSTRING_TYPE — PRI yes, IA5 no, T61 yes, BMP yes, UNI no, UTF8 yes
  • PKCS9STRING_TYPE — PRI yes, IA5 yes, T61 yes, BMP yes, UNI no, UTF8 yes

okay now the actual flow, pay attention 👑

  • if out is NULL, then inform, inbytes, and in get validated and the output type gets figured out and returned — but literally nothing is copied. it's giving window shopping.
  • otherwise, if *out is NULL, a brand new output object of the output type is allocated, and a pointer to it is dropped into *out.
  • otherwise, **out is used as the output object. any data already sitting in it gets freed, and its type gets changed to the output type. out with the old, in with the new 💅
  • finally, in is copied into the output object, changing the character encoding if inform doesn't match whatever encoding the output type uses. slay.

ASN1_mbstring_ncopy() is the same deal, except the number of characters in in gets restricted to the range from minchars to maxchars, inclusive. and if maxchars is 0, there's no upper limit on characters at all — unlimited characters, no cap (well, no max cap 😌).

ASN1_STRING_set_by_NID() is also similar, but with these differences, and yes you need all of them:

  • if out is NULL, a new output object is allocated and returned instead of skipping the copying. so no window shopping here, we're actually buying.
  • if nid has a global string table entry that you can retrieve with ASN1_STRING_TABLE_get(3), then mask, minchars, and maxchars are taken from that string table entry. for some values of nid, an additional global mask gets AND'ed into the mask before it's used. the default value of that global mask is B_ASN1_UTF8STRING.
  • if nid has no global string table entry, then B_ASN1_PRINTABLESTRING | B_ASN1_T61STRING | B_ASN1_BMPSTRING | B_ASN1_UTF8STRING is used instead of the mask from the table, and the global mask also gets AND'ed into it. bestie gets the fallback fit.
  • 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. iykyk.

ASN1_STRING_set_default_mask() sets the global mask used by ASN1_STRING_set_by_NID() to whatever you pass as the mask argument. simple as.

ASN1_STRING_set_default_mask_asc() sets the global mask like this:

  • "default" — anything
  • "nombstr" — anything except B_ASN1_BMPSTRING | B_ASN1_UTF8STRING
  • "pkix" — anything except B_ASN1_T61STRING
  • "utf8only" — B_ASN1_UTF8STRING

and if the maskname argument starts with the substring "MASK:", then the rest of it gets interpreted as an unsigned long value using strtoul(3). sneaky but valid ✨

ASN1_tag2bit() translates ASN.1 data types to type bits, and here's the entire roster, no skipping:

  • 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

and in typical usage? the calling code calculates the bitwise AND of the return value and a mask describing the data types the calling code is willing to use. if the result of that AND operation is non-zero, the data type is adequate — and if it's zero, the calling code may need to raise an error. that's the whole vibe check right there 🔥

🦋 RETURN VALUES 🦋

ASN1_mbstring_copy() and ASN1_mbstring_ncopy() return the V_ASN1_* constant representing the output type, or -1 if:

  • inform is invalid,
  • inbytes or in is invalid for the inform encoding,
  • in contains an UTF-16 surrogate, which is unsupported even for input using the UTF-16 encoding (yes, even then 😭),
  • or memory allocation fails.

ASN1_mbstring_ncopy() also returns -1 if in contains fewer than minchars or more than maxchars characters. length restrictions are real.

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. that's it, that's the whole function, and honestly? queen.

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) — go read those too bestie, they're all connected 🫶

⭐ 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. late bloomer, still iconic 💜

💀 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". yes, it just quietly does a whole different thing. no cap, that's the bug.
passing "default" to ASN1_STRING_set_default_mask_asc() does not restore the default mask. instead, passing "utf8only" does that. the way that is so counterintuitive 😭 remember it, it'll save you.

okay that's the whole page diva 💖 this baby comes to you courtesy of Debian, dated June 8, 2025 — go forth and copy your multibyte strings responsibly, mwah 🎀✨🌸

📦 where this page comes from