#use wml::openssl-macros area=docs page=ASN1_STRING_length

<title>Documents, ASN1_STRING_length(3)</title>

<h1>ASN1_STRING_length(3)</h1>

#use wml::imp::generic

{:
## What's this? [[s|(<STRONG>[^<].+?)</A>(</STRONG><DD>)|$1$2|sg]]
[[s|<P>\s+<P>|<P>|sg]]
[[s|<P>\s+</|</|sg]]
[[s|<DD>\s*<DT>|<DD>&nbsp;<DT>|sg]]
[[s|<DD>\s*</DL>|<DD>&nbsp;</DL>|sg]]
[[s|\[|&#91;|sg]]
[[s|\]|&#93;|sg]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#NOTES">NOTES</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
	<LI><A HREF="#HISTORY">HISTORY</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data - ASN1_STRING
utility functions

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/asn1.h&gt;
</PRE>
<PRE> int ASN1_STRING_length(ASN1_STRING *x);
 unsigned char * ASN1_STRING_data(ASN1_STRING *x);
</PRE>
<PRE> ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
</PRE>
<PRE> int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
</PRE>
<PRE> int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
</PRE>
<PRE> int ASN1_STRING_type(ASN1_STRING *x);
</PRE>
<PRE> int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
These functions allow an <STRONG>ASN1_STRING</STRONG> structure to be manipulated.

</P>
<P>
<CODE>ASN1_STRING_length()</CODE> returns the length of the content of <STRONG>x</STRONG>.

</P>
<P>
<CODE>ASN1_STRING_data()</CODE> returns an internal pointer to the data of <STRONG>x</STRONG>. Since this is an internal pointer it should <STRONG>not</STRONG> be freed or modified in any way.

</P>
<P>
<CODE>ASN1_STRING_dup()</CODE> returns a copy of the structure <STRONG>a</STRONG>.

</P>
<P>
<CODE>ASN1_STRING_cmp()</CODE> compares <STRONG>a</STRONG> and <STRONG>b</STRONG> returning 0 if the two are identical. The string types and content are
compared.

</P>
<P>
<CODE>ASN1_STRING_set()</CODE> sets the data of string <STRONG>str</STRONG> to the buffer
<STRONG>data</STRONG> or length <STRONG>len</STRONG>. The supplied data is copied. If <STRONG>len</STRONG>
is -1 then the length is determined by <CODE>strlen(data).</CODE>

</P>
<P>
<CODE>ASN1_STRING_type()</CODE> returns the type of <STRONG>x</STRONG>, using standard constants such as <STRONG>V_ASN1_OCTET_STRING</STRONG>.

</P>
<P>
<CODE>ASN1_STRING_to_UTF8()</CODE> converts the string <STRONG>in</STRONG> to UTF8 format, the converted data is allocated in a buffer in <STRONG>*out</STRONG>. The length of
<STRONG>out</STRONG> is returned or a negative error code. The buffer <STRONG>*out</STRONG>
should be free using <CODE>OPENSSL_free().</CODE>

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
Almost all ASN1 types in OpenSSL are represented as an <STRONG>ASN1_STRING</STRONG>
structure. Other types such as <STRONG>ASN1_OCTET_STRING</STRONG> are simply typedefed to <STRONG>ASN1_STRING</STRONG> and the functions call the <STRONG>ASN1_STRING</STRONG> equivalents.
<STRONG>ASN1_STRING</STRONG> is also used for some <STRONG>CHOICE</STRONG> types which consist entirely of primitive string types such as <STRONG>DirectoryString</STRONG> and
<STRONG>Time</STRONG>.

</P>
<P>
These functions should <STRONG>not</STRONG> be used to examine or modify <STRONG>ASN1_INTEGER</STRONG>
or <STRONG>ASN1_ENUMERATED</STRONG> types: the relevant <STRONG>INTEGER</STRONG> or <STRONG>ENUMERATED</STRONG>
utility functions should be used instead.

</P>
<P>
In general it cannot be assumed that the data returned by
<CODE>ASN1_STRING_data()</CODE> is null terminated or does not contain
embedded nulls. The actual format of the data will depend on the actual
string type itself: for example for and IA5String the data will be ASCII,
for a BMPString two bytes per character in big endian format, UTF8String
will be in UTF8 format.

</P>
<P>
Similar care should be take to ensure the data is in the correct format
when calling <CODE>ASN1_STRING_set().</CODE>

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../crypto/ERR_get_error.html#">ERR_get_error(3)</A>



</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
:}