--- name: "libressl-ASN1_STRING_length" 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_STRING_length" --- # libressl-ASN1\_STRING\_length(3) ASN1\_STRING utility functions ## NAME **ASN1\_STRING\_cmp**, **ASN1\_OCTET\_STRING\_cmp**, **ASN1\_STRING\_dup**, **ASN1\_OCTET\_STRING\_dup**, **ASN1\_STRING\_get0\_data**, **ASN1\_STRING\_length**, **ASN1\_STRING\_length\_set**, **ASN1\_STRING\_set0**, **ASN1\_STRING\_set**, **ASN1\_OCTET\_STRING\_set**, **ASN1\_STRING\_copy**, **ASN1\_STRING\_to\_UTF8**, **ASN1\_STRING\_type**, **ASN1\_STRING\_data** – ASN1\_STRING utility functions ## SYNOPSIS Crypto Library (libcrypto, -lcrypto) **#include \** *int*\ **ASN1\_STRING\_cmp**(*const ASN1\_STRING \*a*, *const ASN1\_STRING \*b*); *int*\ **ASN1\_OCTET\_STRING\_cmp**(*const ASN1\_OCTET\_STRING \*a*, *const ASN1\_OCTET\_STRING \*b*); *ASN1\_STRING* *\**\ **ASN1\_STRING\_dup**(*const ASN1\_STRING \*a*); *ASN1\_OCTET\_STRING* *\**\ **ASN1\_OCTET\_STRING\_dup**(*const ASN1\_OCTET\_STRING \*a*); *const* *unsigned* *char* *\**\ **ASN1\_STRING\_get0\_data**(*const ASN1\_STRING \*x*); *int*\ **ASN1\_STRING\_length**(*const ASN1\_STRING \*x*); *void*\ **ASN1\_STRING\_length\_set**(*ASN1\_STRING \*x*, *int len*); *void*\ **ASN1\_STRING\_set0**(*ASN1\_STRING \*str*, *void \*data*, *int len*); *int*\ **ASN1\_STRING\_set**(*ASN1\_STRING \*str*, *const void \*data*, *int len*); *int*\ **ASN1\_OCTET\_STRING\_set**(*ASN1\_OCTET\_STRING \*str*, *const unsigned char \*data*, *int len*); *int*\ **ASN1\_STRING\_copy**(*ASN1\_STRING \*dst*, *const ASN1\_STRING \*src*); *int*\ **ASN1\_STRING\_to\_UTF8**(*unsigned char \*\*out*, *const ASN1\_STRING \*in*); *int*\ **ASN1\_STRING\_type**(*const ASN1\_STRING \*x*); Deprecated: *unsigned* *char* *\**\ **ASN1\_STRING\_data**(*ASN1\_STRING \*x*); ## DESCRIPTION These functions manipulate *ASN1\_STRING* structures. **ASN1\_STRING\_cmp**() compares the type, the length, and the content of *a* and *b*. **ASN1\_OCTET\_STRING\_cmp**() does exactly the same as **ASN1\_STRING\_cmp**() without providing any type safety. **ASN1\_STRING\_dup**() allocates a new *ASN1\_STRING* object and copies the type, length, data, and flags from *a* into it. **ASN1\_OCTET\_STRING\_dup**() does exactly the same as **ASN1\_STRING\_dup**() without providing any type safety. **ASN1\_STRING\_get0\_data**() returns an internal pointer to the data of *x*. It should not be freed or modified in any way. **ASN1\_STRING\_length**() returns the length attribute of *x*, measured in bytes. **ASN1\_STRING\_length\_set**() sets the length attribute of *x* to *len*. It may put *x* into an inconsistent internal state. **ASN1\_STRING\_set0**() frees any data stored in *str*, sets the length attribute to *len* bytes, and sets the data attribute to *data*, transferring ownership, without doing any validation. **ASN1\_STRING\_set**() sets the length attribute of *str* to *len* and copies that number of bytes from *data* into *str*, overwriting any previous data. If *len* is -1, then **strlen**(*data*) is used instead of *len*. If *data* is NULL, the content of *str* remains uninitialized; that is not considered an error unless *len* is negative. **ASN1\_OCTET\_STRING\_set**() does exactly the same as **ASN1\_STRING\_set**() without providing any type safety. **ASN1\_STRING\_copy**() copies the length and data of *src* into *dst* using **ASN1\_STRING\_set**() and changes the type and flags of *dst* to match the type and flags of *src*. **ASN1\_STRING\_to\_UTF8**() converts the string *in* to UTF-8 format. The converted data is copied into a newly allocated buffer \**out*. The buffer \**out* should be freed using [free(3)](/free/3.md). **ASN1\_STRING\_type**() returns the type of *x*. If the bit V\_ASN1\_NEG is set in the return value, *x* is an ASN.1 INTEGER or ENUMERATED object with a negative value. **ASN1\_STRING\_data**() is similar to **ASN1\_STRING\_get0\_data**() except that the returned value is not constant. This function is deprecated. Applications should use **ASN1\_STRING\_get0\_data**() instead. Almost all ASN.1 types are represented as *ASN1\_STRING* structures. Other types such as *ASN1\_OCTET\_STRING* are simply typedefed to *ASN1\_STRING* and the functions call the *ASN1\_STRING* equivalents. *ASN1\_STRING* is also used for some CHOICE types which consist entirely of primitive string types such as *DirectoryString* and *Time*. These functions should *not* be used to examine or modify *ASN1\_INTEGER* or *ASN1\_ENUMERATED* types: the relevant INTEGER or ENUMERATED utility functions should be used instead. In general it cannot be assumed that the data returned by **ASN1\_STRING\_get0\_data**() and **ASN1\_STRING\_data**() is NUL terminated, and it may contain embedded NUL characters. The format of the data depends on the string type: for example for an *IA5String* the data contains ASCII characters, for a *BMPString* two bytes per character in big endian format, and for a *UTF8String* UTF-8 characters. Similar care should be taken to ensure the data is in the correct format when calling **ASN1\_STRING\_set**() or **ASN1\_STRING\_set0**(). ## RETURN VALUES **ASN1\_STRING\_cmp**() and **ASN1\_OCTET\_STRING\_cmp**() return 0 if the type, the length, and the content of *a* and *b* agree, or a non-zero value otherwise. In contrast to [strcmp(3)](/strcmp/3.md), the sign of the return value does not indicate lexicographical ordering. **ASN1\_STRING\_get0\_data**() and **ASN1\_STRING\_data**() return an internal pointer to the data of *x*. **ASN1\_STRING\_dup**() and **ASN1\_OCTET\_STRING\_dup**() return a pointer to a newly allocated *ASN1\_STRING* structure or NULL if an error occurred. **ASN1\_STRING\_length**() returns a number of bytes. **ASN1\_STRING\_set**(), **ASN1\_OCTET\_STRING\_set**(), and **ASN1\_STRING\_copy**() return 1 on success or 0 on failure. They fail if memory allocation fails. **ASN1\_STRING\_set**() and **ASN1\_OCTET\_STRING\_set**() also fail if *data* is NULL and *len* is -1 in the same call. **ASN1\_STRING\_copy**() also fails if *src* is NULL. **ASN1\_STRING\_to\_UTF8**() returns the number of bytes in the output buffer \**out*, or a negative number if an error occurred. **ASN1\_STRING\_type**() returns an integer constant, for example V\_ASN1\_OCTET\_STRING or V\_ASN1\_NEG\_INTEGER. In some cases of failure of **ASN1\_STRING\_dup**(), **ASN1\_STRING\_set**(), and **ASN1\_STRING\_to\_UTF8**(), the reason can be determined with ERR\_get\_error(3). ## SEE ALSO a2i\_ASN1\_STRING(3), a2i\_ipadd(3), ASN1\_BIT\_STRING\_set(3), ASN1\_mbstring\_copy(3), ASN1\_PRINTABLE\_type(3), ASN1\_STRING\_new(3), ASN1\_UNIVERSALSTRING\_to\_string(3), s2i\_ASN1\_INTEGER(3) ## HISTORY **ASN1\_STRING\_cmp**(), **ASN1\_STRING\_dup**(), **ASN1\_STRING\_set**(), and **ASN1\_OCTET\_STRING\_set**() first appeared in SSLeay 0.6.5. **ASN1\_OCTET\_STRING\_cmp**(), **ASN1\_STRING\_data**(), **ASN1\_OCTET\_STRING\_dup**(), and **ASN1\_STRING\_type**() first appeared in SSLeay 0.8.0. **ASN1\_STRING\_length**() first appeared in SSLeay 0.9.0. All these functions have been available since OpenBSD 2.4. **ASN1\_STRING\_length\_set**() first appeared in OpenSSL 0.9.5 and has been available since OpenBSD 2.7. **ASN1\_STRING\_to\_UTF8**() first appeared in OpenSSL 0.9.6 and has been available since OpenBSD 2.9. **ASN1\_STRING\_set0**() first appeared in OpenSSL 0.9.8h and has been available since OpenBSD 4.5. **ASN1\_STRING\_copy**() first appeared in OpenSSL 1.0.0 and has been available since OpenBSD 4.9. **ASN1\_STRING\_get0\_data**() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 6.3. ## BUGS **ASN1\_OCTET\_STRING\_cmp**(), **ASN1\_OCTET\_STRING\_dup**(), and **ASN1\_OCTET\_STRING\_set**() do not check whether their arguments are really of the type V\_ASN1\_OCTET\_STRING. They may report success even if their arguments are of a wrong type. Consequently, even in case of success, the return value of **ASN1\_OCTET\_STRING\_dup**() is not guaranteed to be of the type V\_ASN1\_OCTET\_STRING either.