1.\" $OpenBSD: ASN1_STRING_print_ex.3,v 1.17 2021/07/11 19:03:45 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: July 11 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.Nd ASN1_STRING output routines 62.Sh SYNOPSIS 63.In openssl/asn1.h 64.Ft int 65.Fo ASN1_STRING_print_ex 66.Fa "BIO *out" 67.Fa "const ASN1_STRING *str" 68.Fa "unsigned long flags" 69.Fc 70.Ft int 71.Fo ASN1_STRING_print_ex_fp 72.Fa "FILE *fp" 73.Fa "const ASN1_STRING *str" 74.Fa "unsigned long flags" 75.Fc 76.Ft int 77.Fo ASN1_STRING_print 78.Fa "BIO *out" 79.Fa "const ASN1_STRING *str" 80.Fc 81.Ft const char * 82.Fo ASN1_tag2str 83.Fa "int tag" 84.Fc 85.Sh DESCRIPTION 86These functions output an 87.Vt ASN1_STRING 88structure. 89.Vt ASN1_STRING 90is used to 91represent all the ASN.1 string types. 92.Pp 93.Fn ASN1_STRING_print_ex 94outputs 95.Fa str 96to 97.Fa out , 98the format being determined by the options 99.Fa flags . 100.Fn ASN1_STRING_print_ex_fp 101is identical except it outputs to 102.Fa fp 103instead. 104.Pp 105.Fn ASN1_STRING_print 106prints 107.Fa str 108to 109.Fa out 110but using a different format to 111.Fn ASN1_STRING_print_ex . 112It replaces unprintable characters (other than CR, LF) with 113.Sq \&. . 114.Pp 115.Fn ASN1_tag2str 116returns a human-readable name of the specified ASN.1 117.Fa tag . 118.Pp 119.Fn ASN1_STRING_print 120is a deprecated function which should be avoided; use 121.Fn ASN1_STRING_print_ex 122instead. 123.Pp 124Although there are a large number of options, 125.Dv ASN1_STRFLGS_RFC2253 126is often suitable, or on UTF-8 terminals 127.Dv ASN1_STRFLGS_RFC2253 128and 129.Pf ~ Dv ASN1_STRFLGS_ESC_MSB . 130.Pp 131The complete set of supported options for 132.Fa flags 133is listed below. 134.Pp 135Various characters can be escaped. 136If 137.Dv ASN1_STRFLGS_ESC_2253 138is set, the characters determined by RFC 2253 are escaped. 139If 140.Dv ASN1_STRFLGS_ESC_CTRL 141is set, control characters are escaped. 142If 143.Dv ASN1_STRFLGS_ESC_MSB 144is set, characters with the MSB set are escaped: this option should 145.Em not 146be used if the terminal correctly interprets UTF-8 sequences. 147.Pp 148Escaping takes several forms. 149If the character being escaped is a 16-bit character then the form "\eUXXXX" 150is used using exactly four characters for the hex representation. 151If it is 32 bits then "\eWXXXXXXXX" is used using eight characters 152of its hex representation. 153These forms will only be used if UTF-8 conversion is not set (see below). 154.Pp 155Printable characters are normally escaped using the backslash 156.Pq Sq \e 157character. 158If 159.Dv ASN1_STRFLGS_ESC_QUOTE 160is set, then the whole string is instead surrounded by double quote 161characters: this is arguably more readable than the backslash notation. 162Other characters use the "\eXX" using exactly two characters of the hex 163representation. 164.Pp 165If 166.Dv ASN1_STRFLGS_UTF8_CONVERT 167is set, then characters are converted to UTF-8 format first. 168If the terminal supports the display of UTF-8 sequences then this 169option will correctly display multi-byte characters. 170.Pp 171If 172.Dv ASN1_STRFLGS_IGNORE_TYPE 173is set, then the string type is not interpreted at all: 174everything is assumed to be one byte per character. 175This is primarily for debugging purposes and can result 176in confusing output in multi-character strings. 177.Pp 178If 179.Dv ASN1_STRFLGS_SHOW_TYPE 180is set, then the string type itself is printed before its value 181(for example "BMPSTRING"), using 182.Fn ASN1_tag2str . 183.Pp 184Instead of being interpreted the contents of a string can be "dumped": 185this just outputs the value of the string using the form #XXXX 186using hex format for each octet. 187.Pp 188If 189.Dv ASN1_STRFLGS_DUMP_ALL 190is set, then any type is dumped. 191.Pp 192Normally non-character string types (such as OCTET STRING) 193are assumed to be one byte per character; if 194.Dv ASN1_STRFLGS_DUMP_UNKNOWN 195is set, then they will be dumped instead. 196.Pp 197When a type is dumped normally just the content octets are printed; if 198.Dv ASN1_STRFLGS_DUMP_DER 199is set, then the complete encoding is dumped 200instead (including tag and length octets). 201.Pp 202.Dv ASN1_STRFLGS_RFC2253 203includes all the flags required by RFC 2253. 204It is equivalent to 205.Dv ASN1_STRFLGS_ESC_2253 | 206.Dv ASN1_STRFLGS_ESC_CTRL | 207.Dv ASN1_STRFLGS_ESC_MSB | 208.Dv ASN1_STRFLGS_UTF8_CONVERT | 209.Dv ASN1_STRFLGS_DUMP_UNKNOWN | 210.Dv ASN1_STRFLGS_DUMP_DER . 211.Sh RETURN VALUES 212.Fn ASN1_STRING_print_ex 213and 214.Fn ASN1_STRING_print_ex_fp 215return the number of characters written or \-1 if an error occurred. 216.Pp 217.Fn ASN1_STRING_print 218returns 1 on success or 0 on error. 219.Pp 220.Fn ASN1_tag2str 221returns a static string. 222.Sh SEE ALSO 223.Xr ASN1_parse_dump 3 , 224.Xr ASN1_STRING_new 3 , 225.Xr X509_NAME_print_ex 3 , 226.Xr X509_signature_dump 3 227.Sh HISTORY 228.Fn ASN1_STRING_print 229first appeared in SSLeay 0.6.5 and has been available since 230.Ox 2.4 . 231.Pp 232.Fn ASN1_tag2str 233first appeared in OpenSSL 0.9.5 and has been available since 234.Ox 2.7 . 235.Pp 236.Fn ASN1_STRING_print_ex 237and 238.Fn ASN1_STRING_print_ex_fp 239first appeared in OpenSSL 0.9.6 and have been available since 240.Ox 2.9 . 241