1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, 6*4724848cSchristosASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data, 7*4724848cSchristosASN1_STRING_to_UTF8 - ASN1_STRING utility functions 8*4724848cSchristos 9*4724848cSchristos=head1 SYNOPSIS 10*4724848cSchristos 11*4724848cSchristos #include <openssl/asn1.h> 12*4724848cSchristos 13*4724848cSchristos int ASN1_STRING_length(ASN1_STRING *x); 14*4724848cSchristos const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x); 15*4724848cSchristos unsigned char * ASN1_STRING_data(ASN1_STRING *x); 16*4724848cSchristos 17*4724848cSchristos ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a); 18*4724848cSchristos 19*4724848cSchristos int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b); 20*4724848cSchristos 21*4724848cSchristos int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len); 22*4724848cSchristos 23*4724848cSchristos int ASN1_STRING_type(const ASN1_STRING *x); 24*4724848cSchristos 25*4724848cSchristos int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in); 26*4724848cSchristos 27*4724848cSchristos=head1 DESCRIPTION 28*4724848cSchristos 29*4724848cSchristosThese functions allow an B<ASN1_STRING> structure to be manipulated. 30*4724848cSchristos 31*4724848cSchristosASN1_STRING_length() returns the length of the content of B<x>. 32*4724848cSchristos 33*4724848cSchristosASN1_STRING_get0_data() returns an internal pointer to the data of B<x>. 34*4724848cSchristosSince this is an internal pointer it should B<not> be freed or 35*4724848cSchristosmodified in any way. 36*4724848cSchristos 37*4724848cSchristosASN1_STRING_data() is similar to ASN1_STRING_get0_data() except the 38*4724848cSchristosreturned value is not constant. This function is deprecated: 39*4724848cSchristosapplications should use ASN1_STRING_get0_data() instead. 40*4724848cSchristos 41*4724848cSchristosASN1_STRING_dup() returns a copy of the structure B<a>. 42*4724848cSchristos 43*4724848cSchristosASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two 44*4724848cSchristosare identical. The string types and content are compared. 45*4724848cSchristos 46*4724848cSchristosASN1_STRING_set() sets the data of string B<str> to the buffer 47*4724848cSchristosB<data> or length B<len>. The supplied data is copied. If B<len> 48*4724848cSchristosis -1 then the length is determined by strlen(data). 49*4724848cSchristos 50*4724848cSchristosASN1_STRING_type() returns the type of B<x>, using standard constants 51*4724848cSchristossuch as B<V_ASN1_OCTET_STRING>. 52*4724848cSchristos 53*4724848cSchristosASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the 54*4724848cSchristosconverted data is allocated in a buffer in B<*out>. The length of 55*4724848cSchristosB<out> is returned or a negative error code. The buffer B<*out> 56*4724848cSchristosshould be freed using OPENSSL_free(). 57*4724848cSchristos 58*4724848cSchristos=head1 NOTES 59*4724848cSchristos 60*4724848cSchristosAlmost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING> 61*4724848cSchristosstructure. Other types such as B<ASN1_OCTET_STRING> are simply typedef'ed 62*4724848cSchristosto B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents. 63*4724848cSchristosB<ASN1_STRING> is also used for some B<CHOICE> types which consist 64*4724848cSchristosentirely of primitive string types such as B<DirectoryString> and 65*4724848cSchristosB<Time>. 66*4724848cSchristos 67*4724848cSchristosThese functions should B<not> be used to examine or modify B<ASN1_INTEGER> 68*4724848cSchristosor B<ASN1_ENUMERATED> types: the relevant B<INTEGER> or B<ENUMERATED> 69*4724848cSchristosutility functions should be used instead. 70*4724848cSchristos 71*4724848cSchristosIn general it cannot be assumed that the data returned by ASN1_STRING_data() 72*4724848cSchristosis null terminated or does not contain embedded nulls. The actual format 73*4724848cSchristosof the data will depend on the actual string type itself: for example 74*4724848cSchristosfor an IA5String the data will be ASCII, for a BMPString two bytes per 75*4724848cSchristoscharacter in big endian format, and for a UTF8String it will be in UTF8 format. 76*4724848cSchristos 77*4724848cSchristosSimilar care should be take to ensure the data is in the correct format 78*4724848cSchristoswhen calling ASN1_STRING_set(). 79*4724848cSchristos 80*4724848cSchristos=head1 RETURN VALUES 81*4724848cSchristos 82*4724848cSchristosASN1_STRING_length() returns the length of the content of B<x>. 83*4724848cSchristos 84*4724848cSchristosASN1_STRING_get0_data() and ASN1_STRING_data() return an internal pointer to 85*4724848cSchristosthe data of B<x>. 86*4724848cSchristos 87*4724848cSchristosASN1_STRING_dup() returns a valid B<ASN1_STRING> structure or B<NULL> if an 88*4724848cSchristoserror occurred. 89*4724848cSchristos 90*4724848cSchristosASN1_STRING_cmp() returns an integer greater than, equal to, or less than 0, 91*4724848cSchristosaccording to whether B<a> is greater than, equal to, or less than B<b>. 92*4724848cSchristos 93*4724848cSchristosASN1_STRING_set() returns 1 on success or 0 on error. 94*4724848cSchristos 95*4724848cSchristosASN1_STRING_type() returns the type of B<x>. 96*4724848cSchristos 97*4724848cSchristosASN1_STRING_to_UTF8() returns the number of bytes in output string B<out> or a 98*4724848cSchristosnegative value if an error occurred. 99*4724848cSchristos 100*4724848cSchristos=head1 SEE ALSO 101*4724848cSchristos 102*4724848cSchristosL<ERR_get_error(3)> 103*4724848cSchristos 104*4724848cSchristos=head1 COPYRIGHT 105*4724848cSchristos 106*4724848cSchristosCopyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved. 107*4724848cSchristos 108*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 109*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 110*4724848cSchristosin the file LICENSE in the source distribution or at 111*4724848cSchristosL<https://www.openssl.org/source/license.html>. 112*4724848cSchristos 113*4724848cSchristos=cut 114