1109998Smarkm=pod 2109998Smarkm 3109998Smarkm=head1 NAME 4109998Smarkm 5109998SmarkmASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, 6109998SmarkmASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data - 7109998SmarkmASN1_STRING utility functions 8109998Smarkm 9109998Smarkm=head1 SYNOPSIS 10109998Smarkm 11215697Ssimon #include <openssl/asn1.h> 12215697Ssimon 13109998Smarkm int ASN1_STRING_length(ASN1_STRING *x); 14109998Smarkm unsigned char * ASN1_STRING_data(ASN1_STRING *x); 15109998Smarkm 16109998Smarkm ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a); 17109998Smarkm 18109998Smarkm int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b); 19109998Smarkm 20109998Smarkm int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len); 21109998Smarkm 22109998Smarkm int ASN1_STRING_type(ASN1_STRING *x); 23109998Smarkm 24109998Smarkm int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in); 25109998Smarkm 26109998Smarkm=head1 DESCRIPTION 27109998Smarkm 28109998SmarkmThese functions allow an B<ASN1_STRING> structure to be manipulated. 29109998Smarkm 30109998SmarkmASN1_STRING_length() returns the length of the content of B<x>. 31109998Smarkm 32109998SmarkmASN1_STRING_data() returns an internal pointer to the data of B<x>. 33109998SmarkmSince this is an internal pointer it should B<not> be freed or 34109998Smarkmmodified in any way. 35109998Smarkm 36109998SmarkmASN1_STRING_dup() returns a copy of the structure B<a>. 37109998Smarkm 38109998SmarkmASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two 39109998Smarkmare identical. The string types and content are compared. 40109998Smarkm 41109998SmarkmASN1_STRING_set() sets the data of string B<str> to the buffer 42109998SmarkmB<data> or length B<len>. The supplied data is copied. If B<len> 43109998Smarkmis -1 then the length is determined by strlen(data). 44109998Smarkm 45109998SmarkmASN1_STRING_type() returns the type of B<x>, using standard constants 46109998Smarkmsuch as B<V_ASN1_OCTET_STRING>. 47109998Smarkm 48109998SmarkmASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the 49109998Smarkmconverted data is allocated in a buffer in B<*out>. The length of 50109998SmarkmB<out> is returned or a negative error code. The buffer B<*out> 51109998Smarkmshould be free using OPENSSL_free(). 52109998Smarkm 53109998Smarkm=head1 NOTES 54109998Smarkm 55109998SmarkmAlmost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING> 56109998Smarkmstructure. Other types such as B<ASN1_OCTET_STRING> are simply typedefed 57109998Smarkmto B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents. 58109998SmarkmB<ASN1_STRING> is also used for some B<CHOICE> types which consist 59109998Smarkmentirely of primitive string types such as B<DirectoryString> and 60109998SmarkmB<Time>. 61109998Smarkm 62109998SmarkmThese functions should B<not> be used to examine or modify B<ASN1_INTEGER> 63109998Smarkmor B<ASN1_ENUMERATED> types: the relevant B<INTEGER> or B<ENUMERATED> 64109998Smarkmutility functions should be used instead. 65109998Smarkm 66109998SmarkmIn general it cannot be assumed that the data returned by ASN1_STRING_data() 67109998Smarkmis null terminated or does not contain embedded nulls. The actual format 68109998Smarkmof the data will depend on the actual string type itself: for example 69109998Smarkmfor and IA5String the data will be ASCII, for a BMPString two bytes per 70109998Smarkmcharacter in big endian format, UTF8String will be in UTF8 format. 71109998Smarkm 72109998SmarkmSimilar care should be take to ensure the data is in the correct format 73109998Smarkmwhen calling ASN1_STRING_set(). 74109998Smarkm 75109998Smarkm=head1 RETURN VALUES 76109998Smarkm 77109998Smarkm=head1 SEE ALSO 78109998Smarkm 79109998SmarkmL<ERR_get_error(3)|ERR_get_error(3)> 80109998Smarkm 81109998Smarkm=head1 HISTORY 82109998Smarkm 83109998Smarkm=cut 84