1.\" $OpenBSD: ASN1_STRING_print_ex.3,v 1.18 2021/12/14 19:36:18 schwarze Exp $ 2.\" full merge up to: OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400 3.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 4.\" 5.\" This file was written by Dr. Stephen Henson. 6.\" Copyright (c) 2002, 2004, 2007, 2013, 2016, 2017 The OpenSSL Project. 7.\" All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in 18.\" the documentation and/or other materials provided with the 19.\" distribution. 20.\" 21.\" 3. All advertising materials mentioning features or use of this 22.\" software must display the following acknowledgment: 23.\" "This product includes software developed by the OpenSSL Project 24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 25.\" 26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 27.\" endorse or promote products derived from this software without 28.\" prior written permission. For written permission, please contact 29.\" openssl-core@openssl.org. 30.\" 31.\" 5. Products derived from this software may not be called "OpenSSL" 32.\" nor may "OpenSSL" appear in their names without prior written 33.\" permission of the OpenSSL Project. 34.\" 35.\" 6. Redistributions of any form whatsoever must retain the following 36.\" acknowledgment: 37.\" "This product includes software developed by the OpenSSL Project 38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 39.\" 40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 51.\" OF THE POSSIBILITY OF SUCH DAMAGE. 52.\" 53.Dd $Mdocdate: December 14 2021 $ 54.Dt ASN1_STRING_PRINT_EX 3 55.Os 56.Sh NAME 57.Nm ASN1_STRING_print_ex , 58.Nm ASN1_STRING_print_ex_fp , 59.Nm ASN1_STRING_print , 60.Nm ASN1_tag2str 61.\" M_ASN1_OCTET_STRING_print is a deprecated alias, intentionally undocumented 62.Nd ASN1_STRING output routines 63.Sh SYNOPSIS 64.In openssl/asn1.h 65.Ft int 66.Fo ASN1_STRING_print_ex 67.Fa "BIO *out" 68.Fa "const ASN1_STRING *str" 69.Fa "unsigned long flags" 70.Fc 71.Ft int 72.Fo ASN1_STRING_print_ex_fp 73.Fa "FILE *fp" 74.Fa "const ASN1_STRING *str" 75.Fa "unsigned long flags" 76.Fc 77.Ft int 78.Fo ASN1_STRING_print 79.Fa "BIO *out" 80.Fa "const ASN1_STRING *str" 81.Fc 82.Ft const char * 83.Fo ASN1_tag2str 84.Fa "int tag" 85.Fc 86.Sh DESCRIPTION 87These functions output an 88.Vt ASN1_STRING 89structure. 90.Vt ASN1_STRING 91is used to 92represent all the ASN.1 string types. 93.Pp 94.Fn ASN1_STRING_print_ex 95outputs 96.Fa str 97to 98.Fa out , 99the format being determined by the options 100.Fa flags . 101.Fn ASN1_STRING_print_ex_fp 102is identical except it outputs to 103.Fa fp 104instead. 105.Pp 106.Fn ASN1_STRING_print 107prints 108.Fa str 109to 110.Fa out 111but using a different format to 112.Fn ASN1_STRING_print_ex . 113It replaces unprintable characters (other than CR, LF) with 114.Sq \&. . 115.Pp 116.Fn ASN1_tag2str 117returns a human-readable name of the specified ASN.1 118.Fa tag . 119.Pp 120.Fn ASN1_STRING_print 121is a deprecated function which should be avoided; use 122.Fn ASN1_STRING_print_ex 123instead. 124.Pp 125Although there are a large number of options, 126.Dv ASN1_STRFLGS_RFC2253 127is often suitable, or on UTF-8 terminals 128.Dv ASN1_STRFLGS_RFC2253 129and 130.Pf ~ Dv ASN1_STRFLGS_ESC_MSB . 131.Pp 132The complete set of supported options for 133.Fa flags 134is listed below. 135.Pp 136Various characters can be escaped. 137If 138.Dv ASN1_STRFLGS_ESC_2253 139is set, the characters determined by RFC 2253 are escaped. 140If 141.Dv ASN1_STRFLGS_ESC_CTRL 142is set, control characters are escaped. 143If 144.Dv ASN1_STRFLGS_ESC_MSB 145is set, characters with the MSB set are escaped: this option should 146.Em not 147be used if the terminal correctly interprets UTF-8 sequences. 148.Pp 149Escaping takes several forms. 150If the character being escaped is a 16-bit character then the form "\eUXXXX" 151is used using exactly four characters for the hex representation. 152If it is 32 bits then "\eWXXXXXXXX" is used using eight characters 153of its hex representation. 154These forms will only be used if UTF-8 conversion is not set (see below). 155.Pp 156Printable characters are normally escaped using the backslash 157.Pq Sq \e 158character. 159If 160.Dv ASN1_STRFLGS_ESC_QUOTE 161is set, then the whole string is instead surrounded by double quote 162characters: this is arguably more readable than the backslash notation. 163Other characters use the "\eXX" using exactly two characters of the hex 164representation. 165.Pp 166If 167.Dv ASN1_STRFLGS_UTF8_CONVERT 168is set, then characters are converted to UTF-8 format first. 169If the terminal supports the display of UTF-8 sequences then this 170option will correctly display multi-byte characters. 171.Pp 172If 173.Dv ASN1_STRFLGS_IGNORE_TYPE 174is set, then the string type is not interpreted at all: 175everything is assumed to be one byte per character. 176This is primarily for debugging purposes and can result 177in confusing output in multi-character strings. 178.Pp 179If 180.Dv ASN1_STRFLGS_SHOW_TYPE 181is set, then the string type itself is printed before its value 182(for example "BMPSTRING"), using 183.Fn ASN1_tag2str . 184.Pp 185Instead of being interpreted the contents of a string can be "dumped": 186this just outputs the value of the string using the form #XXXX 187using hex format for each octet. 188.Pp 189If 190.Dv ASN1_STRFLGS_DUMP_ALL 191is set, then any type is dumped. 192.Pp 193Normally non-character string types (such as OCTET STRING) 194are assumed to be one byte per character; if 195.Dv ASN1_STRFLGS_DUMP_UNKNOWN 196is set, then they will be dumped instead. 197.Pp 198When a type is dumped normally just the content octets are printed; if 199.Dv ASN1_STRFLGS_DUMP_DER 200is set, then the complete encoding is dumped 201instead (including tag and length octets). 202.Pp 203.Dv ASN1_STRFLGS_RFC2253 204includes all the flags required by RFC 2253. 205It is equivalent to 206.Dv ASN1_STRFLGS_ESC_2253 | 207.Dv ASN1_STRFLGS_ESC_CTRL | 208.Dv ASN1_STRFLGS_ESC_MSB | 209.Dv ASN1_STRFLGS_UTF8_CONVERT | 210.Dv ASN1_STRFLGS_DUMP_UNKNOWN | 211.Dv ASN1_STRFLGS_DUMP_DER . 212.Sh RETURN VALUES 213.Fn ASN1_STRING_print_ex 214and 215.Fn ASN1_STRING_print_ex_fp 216return the number of characters written or \-1 if an error occurred. 217.Pp 218.Fn ASN1_STRING_print 219returns 1 on success or 0 on error. 220.Pp 221.Fn ASN1_tag2str 222returns a static string. 223.Sh SEE ALSO 224.Xr ASN1_parse_dump 3 , 225.Xr ASN1_STRING_new 3 , 226.Xr X509_NAME_print_ex 3 , 227.Xr X509_signature_dump 3 228.Sh HISTORY 229.Fn ASN1_STRING_print 230first appeared in SSLeay 0.6.5 and has been available since 231.Ox 2.4 . 232.Pp 233.Fn ASN1_tag2str 234first appeared in OpenSSL 0.9.5 and has been available since 235.Ox 2.7 . 236.Pp 237.Fn ASN1_STRING_print_ex 238and 239.Fn ASN1_STRING_print_ex_fp 240first appeared in OpenSSL 0.9.6 and have been available since 241.Ox 2.9 . 242