1.Dd $Mdocdate: September 9 2015 $ 2.Dt ASN1_STRING_LENGTH 3 3.Os 4.Sh NAME 5.Nm ASN1_STRING_cmp , 6.Nm ASN1_STRING_data , 7.Nm ASN1_STRING_dup , 8.Nm ASN1_STRING_length , 9.Nm ASN1_STRING_length_set , 10.Nm ASN1_STRING_set , 11.Nm ASN1_STRING_to_UTF8 , 12.Nm ASN1_STRING_type 13.Nd ASN1_STRING utility functions 14.Sh SYNOPSIS 15.In openssl/asn1.h 16.Ft int 17.Fo ASN1_STRING_cmp 18.Fa "ASN1_STRING *a" 19.Fa "ASN1_STRING *b" 20.Fc 21.Ft unsigned char * 22.Fo ASN1_STRING_data 23.Fa "ASN1_STRING *x" 24.Fc 25.Ft ASN1_STRING * 26.Fo ASN1_STRING_dup 27.Fa "ASN1_STRING *a" 28.Fc 29.Ft int 30.Fo ASN1_STRING_length 31.Fa "ASN1_STRING *x" 32.Fc 33.Ft void 34.Fo ASN1_STRING_length_set 35.Fa "ASN1_STRING *x" 36.Fa "int len" 37.Fc 38.Ft int 39.Fo ASN1_STRING_set 40.Fa "ASN1_STRING *str" 41.Fa "const void *data" 42.Fa "int len" 43.Fc 44.Ft int 45.Fo ASN1_STRING_to_UTF8 46.Fa "unsigned char **out" 47.Fa "ASN1_STRING *in" 48.Fc 49.Ft int 50.Fo ASN1_STRING_type 51.Fa "ASN1_STRING *x" 52.Fc 53.Sh DESCRIPTION 54These functions manipulate 55.Vt ASN1_STRING 56structures. 57.Pp 58.Fn ASN1_STRING_cmp 59compares 60.Fa a 61and 62.Fa b 63and returns 0 if the two are identical. 64The string types and the content are compared. 65.Pp 66.Fn ASN1_STRING_data 67returns an internal pointer to the data of 68.Fa x . 69Since this is an internal pointer, it should 70.Em not 71be freed or modified in any way. 72.Pp 73.Fn ASN1_STRING_dup 74returns a copy of the structure 75.Fa a . 76.Pp 77.Fn ASN1_STRING_length 78returns the length of the content of 79.Fa x . 80.Pp 81.Fn ASN1_STRING_length_set 82sets the length attribute of 83.Fa x 84to 85.Fa len . 86It may put 87.Fa x 88into an inconsistent internal state. 89.Pp 90.Fn ASN1_STRING_set 91sets the data of the string 92.Fa str 93to the buffer 94.Fa data 95of length 96.Fa len . 97The supplied data is copied. 98If 99.Fa len 100is -1 then the length is determined by 101.Fn strlen data . 102.Pp 103.Fn ASN1_STRING_to_UTF8 104converts the string 105.Fa in 106to UTF8 format. 107The converted data is copied into a newly allocated buffer 108.Fa out . 109The length of 110.Fa out 111is returned or a negative error code. 112The buffer 113.Fa out 114should be freed using 115.Xr free 3 . 116.Pp 117.Fn ASN1_STRING_type 118returns the type of 119.Fa x , 120using standard constants such as 121.Dv V_ASN1_OCTET_STRING . 122.Sh NOTES 123Almost all ASN1 types in OpenSSL are represented as 124.Vt ASN1_STRING 125structures. 126Other types such as 127.Vt ASN1_OCTET_STRING 128are simply typedefed to 129.Vt ASN1_STRING 130and the functions call the 131.Vt ASN1_STRING 132equivalents. 133.Vt ASN1_STRING 134is also used for some 135.Sy CHOICE 136types which consist entirely of primitive string types such as 137.Sy DirectoryString 138and 139.Sy Time . 140.Pp 141These functions should 142.Em not 143be used to examine or modify 144.Vt ASN1_INTEGER 145or 146.Vt ASN1_ENUMERATED 147types: the relevant 148.Sy INTEGER 149or 150.Sy ENUMERATED 151utility functions should be used instead. 152.Pp 153In general it cannot be assumed that the data returned by 154.Fn ASN1_STRING_data 155is NUL terminated, and it may contain embedded NUL characters. 156The actual format of the data will depend on the actual string type itself: 157for example for an IA5String the data will be ASCII, 158for a BMPString two bytes per character in big endian format, 159UTF8String will be in UTF8 format. 160.Pp 161Similar care should be take to ensure the data is in the correct format 162when calling 163.Fn ASN1_STRING_set . 164.Sh SEE ALSO 165.Xr ERR_get_error 3 166