1*ebfedea0SLionel Sambuc=pod 2*ebfedea0SLionel Sambuc 3*ebfedea0SLionel Sambuc=head1 NAME 4*ebfedea0SLionel Sambuc 5*ebfedea0SLionel SambucASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, 6*ebfedea0SLionel SambucASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data - 7*ebfedea0SLionel SambucASN1_STRING utility functions 8*ebfedea0SLionel Sambuc 9*ebfedea0SLionel Sambuc=head1 SYNOPSIS 10*ebfedea0SLionel Sambuc 11*ebfedea0SLionel Sambuc #include <openssl/asn1.h> 12*ebfedea0SLionel Sambuc 13*ebfedea0SLionel Sambuc int ASN1_STRING_length(ASN1_STRING *x); 14*ebfedea0SLionel Sambuc unsigned char * ASN1_STRING_data(ASN1_STRING *x); 15*ebfedea0SLionel Sambuc 16*ebfedea0SLionel Sambuc ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a); 17*ebfedea0SLionel Sambuc 18*ebfedea0SLionel Sambuc int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b); 19*ebfedea0SLionel Sambuc 20*ebfedea0SLionel Sambuc int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len); 21*ebfedea0SLionel Sambuc 22*ebfedea0SLionel Sambuc int ASN1_STRING_type(ASN1_STRING *x); 23*ebfedea0SLionel Sambuc 24*ebfedea0SLionel Sambuc int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in); 25*ebfedea0SLionel Sambuc 26*ebfedea0SLionel Sambuc=head1 DESCRIPTION 27*ebfedea0SLionel Sambuc 28*ebfedea0SLionel SambucThese functions allow an B<ASN1_STRING> structure to be manipulated. 29*ebfedea0SLionel Sambuc 30*ebfedea0SLionel SambucASN1_STRING_length() returns the length of the content of B<x>. 31*ebfedea0SLionel Sambuc 32*ebfedea0SLionel SambucASN1_STRING_data() returns an internal pointer to the data of B<x>. 33*ebfedea0SLionel SambucSince this is an internal pointer it should B<not> be freed or 34*ebfedea0SLionel Sambucmodified in any way. 35*ebfedea0SLionel Sambuc 36*ebfedea0SLionel SambucASN1_STRING_dup() returns a copy of the structure B<a>. 37*ebfedea0SLionel Sambuc 38*ebfedea0SLionel SambucASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two 39*ebfedea0SLionel Sambucare identical. The string types and content are compared. 40*ebfedea0SLionel Sambuc 41*ebfedea0SLionel SambucASN1_STRING_set() sets the data of string B<str> to the buffer 42*ebfedea0SLionel SambucB<data> or length B<len>. The supplied data is copied. If B<len> 43*ebfedea0SLionel Sambucis -1 then the length is determined by strlen(data). 44*ebfedea0SLionel Sambuc 45*ebfedea0SLionel SambucASN1_STRING_type() returns the type of B<x>, using standard constants 46*ebfedea0SLionel Sambucsuch as B<V_ASN1_OCTET_STRING>. 47*ebfedea0SLionel Sambuc 48*ebfedea0SLionel SambucASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the 49*ebfedea0SLionel Sambucconverted data is allocated in a buffer in B<*out>. The length of 50*ebfedea0SLionel SambucB<out> is returned or a negative error code. The buffer B<*out> 51*ebfedea0SLionel Sambucshould be free using OPENSSL_free(). 52*ebfedea0SLionel Sambuc 53*ebfedea0SLionel Sambuc=head1 NOTES 54*ebfedea0SLionel Sambuc 55*ebfedea0SLionel SambucAlmost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING> 56*ebfedea0SLionel Sambucstructure. Other types such as B<ASN1_OCTET_STRING> are simply typedefed 57*ebfedea0SLionel Sambucto B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents. 58*ebfedea0SLionel SambucB<ASN1_STRING> is also used for some B<CHOICE> types which consist 59*ebfedea0SLionel Sambucentirely of primitive string types such as B<DirectoryString> and 60*ebfedea0SLionel SambucB<Time>. 61*ebfedea0SLionel Sambuc 62*ebfedea0SLionel SambucThese functions should B<not> be used to examine or modify B<ASN1_INTEGER> 63*ebfedea0SLionel Sambucor B<ASN1_ENUMERATED> types: the relevant B<INTEGER> or B<ENUMERATED> 64*ebfedea0SLionel Sambucutility functions should be used instead. 65*ebfedea0SLionel Sambuc 66*ebfedea0SLionel SambucIn general it cannot be assumed that the data returned by ASN1_STRING_data() 67*ebfedea0SLionel Sambucis null terminated or does not contain embedded nulls. The actual format 68*ebfedea0SLionel Sambucof the data will depend on the actual string type itself: for example 69*ebfedea0SLionel Sambucfor and IA5String the data will be ASCII, for a BMPString two bytes per 70*ebfedea0SLionel Sambuccharacter in big endian format, UTF8String will be in UTF8 format. 71*ebfedea0SLionel Sambuc 72*ebfedea0SLionel SambucSimilar care should be take to ensure the data is in the correct format 73*ebfedea0SLionel Sambucwhen calling ASN1_STRING_set(). 74*ebfedea0SLionel Sambuc 75*ebfedea0SLionel Sambuc=head1 RETURN VALUES 76*ebfedea0SLionel Sambuc 77*ebfedea0SLionel Sambuc=head1 SEE ALSO 78*ebfedea0SLionel Sambuc 79*ebfedea0SLionel SambucL<ERR_get_error(3)|ERR_get_error(3)> 80*ebfedea0SLionel Sambuc 81*ebfedea0SLionel Sambuc=head1 HISTORY 82*ebfedea0SLionel Sambuc 83*ebfedea0SLionel Sambuc=cut 84