1.Dd $Mdocdate: September 9 2015 $ 2.Dt ASN1_STRING_PRINT_EX 3 3.Os 4.Sh NAME 5.Nm ASN1_STRING_print_ex , 6.Nm ASN1_STRING_print_ex_fp , 7.Nm ASN1_STRING_print 8.Nd ASN1_STRING output routines 9.Sh SYNOPSIS 10.In openssl/asn1.h 11.Ft int 12.Fo ASN1_STRING_print_ex 13.Fa "BIO *out" 14.Fa "ASN1_STRING *str" 15.Fa "unsigned long flags" 16.Fc 17.Ft int 18.Fo ASN1_STRING_print_ex_fp 19.Fa "FILE *fp" 20.Fa "ASN1_STRING *str" 21.Fa "unsigned long flags" 22.Fc 23.Ft int 24.Fo ASN1_STRING_print 25.Fa "BIO *out" 26.Fa "ASN1_STRING *str" 27.Fc 28.Sh DESCRIPTION 29These functions output an 30.Vt ASN1_STRING 31structure. 32.Vt ASN1_STRING 33is used to 34represent all the ASN1 string types. 35.Pp 36.Fn ASN1_STRING_print_ex 37outputs 38.Fa str 39to 40.Fa out , 41the format is determined by the options 42.Fa flags . 43.Fn ASN1_STRING_print_ex_fp 44is identical except it outputs to 45.Fa fp 46instead. 47.Pp 48.Fn ASN1_STRING_print 49prints 50.Fa str 51to 52.Fa out 53but using a different format to 54.Fn ASN1_STRING_print_ex . 55It replaces unprintable characters (other than CR, LF) with 56.Sq \&. . 57.Sh NOTES 58.Fn ASN1_STRING_print 59is a legacy function which should be avoided in new 60applications. 61.Pp 62Although there are a large number of options frequently 63.Dv ASN1_STRFLGS_RFC2253 64is suitable, or on UTF8 terminals 65.Dv ASN1_STRFLGS_RFC2253 No & 66.Pf ~ Dv ASN1_STRFLGS_ESC_MSB . 67.Pp 68The complete set of supported options for 69.Fa flags 70is listed below. 71.Pp 72Various characters can be escaped. 73If 74.Dv ASN1_STRFLGS_ESC_2253 75is set, the characters determined by RFC2253 are escaped. 76If 77.Dv ASN1_STRFLGS_ESC_CTRL 78is set, control characters are escaped. 79If 80.Dv ASN1_STRFLGS_ESC_MSB 81is set, characters with the MSB set are escaped: this option should 82.Em not 83be used if the terminal correctly interprets UTF8 sequences. 84.Pp 85Escaping takes several forms. 86.Pp 87If the character being escaped is a 16 bit character then the form "\eUXXXX" 88is used using exactly four characters for the hex representation. 89If it is 32 bits then "\eWXXXXXXXX" is used using eight characters 90of its hex representation. 91These forms will only be used if UTF8 conversion is not set (see below). 92.Pp 93Printable characters are normally escaped using the backslash 94.Pq Sq \e 95character. 96If 97.Dv ASN1_STRFLGS_ESC_QUOTE 98is set, then the whole string is instead surrounded by double quote 99characters: this is arguably more readable than the backslash notation. 100Other characters use the "\eXX" using exactly two characters of the hex 101representation. 102.Pp 103If 104.Dv ASN1_STRFLGS_UTF8_CONVERT 105is set, then characters are converted to UTF8 format first. 106If the terminal supports the display of UTF8 sequences then this 107option will correctly display multi byte characters. 108.Pp 109If 110.Dv ASN1_STRFLGS_IGNORE_TYPE 111is set, then the string type is not interpreted at all: 112everything is assumed to be one byte per character. 113This is primarily for debugging purposes and can result 114in confusing output in multi character strings. 115.Pp 116If 117.Dv ASN1_STRFLGS_SHOW_TYPE 118is set, then the string type itself is printed out before its value 119(for example "BMPSTRING"), this actually uses 120.Fn ASN1_tag2str . 121.Pp 122The content of a string instead of being interpreted can be "dumped": 123this just outputs the value of the string using the form #XXXX 124using hex format for each octet. 125.Pp 126If 127.Dv ASN1_STRFLGS_DUMP_ALL 128is set, then any type is dumped. 129.Pp 130Normally non character string types (such as OCTET STRING) 131are assumed to be one byte per character; if 132.Dv ASN1_STRFLGS_DUMP_UNKNOWN 133is set, then they will be dumped instead. 134.Pp 135When a type is dumped normally just the content octets are printed; if 136.Dv ASN1_STRFLGS_DUMP_DER 137is set, then the complete encoding is dumped 138instead (including tag and length octets). 139.Pp 140.Dv ASN1_STRFLGS_RFC2253 141includes all the flags required by RFC2253. 142It is equivalent to 143.Dv ASN1_STRFLGS_ESC_2253 | 144.Dv ASN1_STRFLGS_ESC_CTRL | 145.Dv ASN1_STRFLGS_ESC_MSB | 146.Dv ASN1_STRFLGS_UTF8_CONVERT | 147.Dv ASN1_STRFLGS_DUMP_UNKNOWN | 148.Dv ASN1_STRFLGS_DUMP_DER . 149.Sh SEE ALSO 150.Xr ASN1_tag2str 3 , 151.Xr X509_NAME_print_ex 3 152