1 files changed, 151 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/ASN1_STRING_print_ex.3 b/src/lib/libcrypto/man/ASN1_STRING_print_ex.3
new file mode 100644
index 0000000000..1d6495d199
--- /dev/null
+++ b/src/lib/libcrypto/man/ASN1_STRING_print_ex.3
@@ -0,0 +1,151 @@
+.Dd July 17, 2014
+.Dt ASN1_STRING_PRINT_EX 3
+.Os
+.Sh NAME
+.Nm ASN1_STRING_print_ex ,
+.Nm ASN1_STRING_print_ex_fp ,
+.Nm ASN1_STRING_print
+.Nd ASN1_STRING output routines
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft int
+.Fo ASN1_STRING_print_ex
+.Fa "BIO *out"
+.Fa "ASN1_STRING *str"
+.Fa "unsigned long flags"
+.Fc
+.Ft int
+.Fo ASN1_STRING_print_ex_fp
+.Fa "FILE *fp"
+.Fa "ASN1_STRING *str"
+.Fa "unsigned long flags"
+.Fc
+.Ft int
+.Fo ASN1_STRING_print
+.Fa "BIO *out"
+.Fa "ASN1_STRING *str"
+.Fc
+.Sh DESCRIPTION
+These functions output an
+.Vt ASN1_STRING
+structure.
+.Vt ASN1_STRING
+is used to
+represent all the ASN1 string types.
+.Pp
+.Fn ASN1_STRING_print_ex
+outputs
+.Fa str
+to
+.Fa out ,
+the format is determined by the options
+.Fa flags .
+.Fn ASN1_STRING_print_ex_fp
+is identical except it outputs to
+.Fa fp
+instead.
+.Pp
+.Fn ASN1_STRING_print
+prints
+.Fa str
+to
+.Fa out
+but using a different format to
+.Fn ASN1_STRING_print_ex .
+It replaces unprintable characters (other than CR, LF) with
+.Sq \&. .
+.Sh NOTES
+.Fn ASN1_STRING_print
+is a legacy function which should be avoided in new
+applications.
+.Pp
+Although there are a large number of options frequently
+.Dv ASN1_STRFLGS_RFC2253
+is suitable, or on UTF8 terminals
+.Dv ASN1_STRFLGS_RFC2253 No &
+.Pf ~ Dv ASN1_STRFLGS_ESC_MSB .
+.Pp
+The complete set of supported options for
+.Fa flags
+is listed below.
+.Pp
+Various characters can be escaped.
+If
+.Dv ASN1_STRFLGS_ESC_2253
+is set, the characters determined by RFC2253 are escaped.
+If
+.Dv ASN1_STRFLGS_ESC_CTRL
+is set, control characters are escaped.
+If
+.Dv ASN1_STRFLGS_ESC_MSB
+is set, characters with the MSB set are escaped: this option should
+.Em not
+be used if the terminal correctly interprets UTF8 sequences.
+.Pp
+Escaping takes several forms.
+.Pp
+If the character being escaped is a 16 bit character then the form "\eUXXXX"
+is used using exactly four characters for the hex representation.
+If it is 32 bits then "\eWXXXXXXXX" is used using eight characters
+of its hex representation.
+These forms will only be used if UTF8 conversion is not set (see below).
+.Pp
+Printable characters are normally escaped using the backslash
+.Pq Sq \e
+character.
+If
+.Dv ASN1_STRFLGS_ESC_QUOTE
+is set, then the whole string is instead surrounded by double quote
+characters: this is arguably more readable than the backslash notation.
+Other characters use the "\eXX" using exactly two characters of the hex
+representation.
+.Pp
+If
+.Dv ASN1_STRFLGS_UTF8_CONVERT
+is set, then characters are converted to UTF8 format first.
+If the terminal supports the display of UTF8 sequences then this
+option will correctly display multi byte characters.
+.Pp
+If
+.Dv ASN1_STRFLGS_IGNORE_TYPE
+is set, then the string type is not interpreted at all:
+everything is assumed to be one byte per character.
+This is primarily for debugging purposes and can result
+in confusing output in multi character strings.
+.Pp
+If
+.Dv ASN1_STRFLGS_SHOW_TYPE
+is set, then the string type itself is printed out before its value
+(for example "BMPSTRING"), this actually uses
+.Fn ASN1_tag2str .
+.Pp
+The content of a string instead of being interpreted can be "dumped":
+this just outputs the value of the string using the form #XXXX
+using hex format for each octet.
+.Pp
+If
+.Dv ASN1_STRFLGS_DUMP_ALL
+is set, then any type is dumped.
+.Pp
+Normally non character string types (such as OCTET STRING)
+are assumed to be one byte per character; if
+.Dv ASN1_STRFLGS_DUMP_UNKNOWN
+is set, then they will be dumped instead.
+.Pp
+When a type is dumped normally just the content octets are printed; if
+.Dv ASN1_STRFLGS_DUMP_DER
+is set, then the complete encoding is dumped
+instead (including tag and length octets).
+.Pp
+.Dv ASN1_STRFLGS_RFC2253
+includes all the flags required by RFC2253.
+It is equivalent to
+.Dv ASN1_STRFLGS_ESC_2253 |
+.Dv ASN1_STRFLGS_ESC_CTRL |
+.Dv ASN1_STRFLGS_ESC_MSB |
+.Dv ASN1_STRFLGS_UTF8_CONVERT |
+.Dv ASN1_STRFLGS_DUMP_UNKNOWN |
+.Dv ASN1_STRFLGS_DUMP_DER .
+.Sh SEE ALSO
+.Xr ASN1_tag2str 3 ,
+.Xr X509_NAME_print_ex 3