diff --git a/asn1c/Makefile.am b/asn1c/Makefile.am index a369de3f..d1527223 100644 --- a/asn1c/Makefile.am +++ b/asn1c/Makefile.am @@ -20,8 +20,6 @@ bin_PROGRAMS = asn1c unber enber noinst_HEADERS = sys-common.h -dist_man1_MANS = asn1c.1 unber.1 enber.1 - dist_check_SCRIPTS = check-xxber.sh check-parsing.sh TESTS_ENVIRONMENT= top_srcdir=${top_srcdir} TESTS = $(dist_check_SCRIPTS) diff --git a/asn1c/asn1c.1 b/asn1c/asn1c.1 deleted file mode 100644 index 5485cc98..00000000 --- a/asn1c/asn1c.1 +++ /dev/null @@ -1,125 +0,0 @@ -.TH asn1c 1 "2014-10-23" "ASN.1 Compiler" -.if n .ad l \" Turn off justifications -.nh \" Turn off hyphenation; can damage formatting in technical documents. -.SH NAME -asn1c \(em the ASN.1 Compiler -.SH SYNOPSIS -asn1c [\fB\-E\fR [\fB-F\fR] | \fB\-P\fR | \fB\-R\fR] - [\fB\-S\fR\fIdir\fR] [\fB-X\fR] - [\fB\-W\fR\fIdebug-\fR...] [\fB\-f\fR\fIoption\fR] [\fB\-gen-\fR\fIoption\fR] [\fB\-pdu=\fR{\fBall\fR|\fBauto\fR|\fIType\fR}\fR] - [\fB\-print-\fR\fIoption\fR] - \fIinput-filenames\fR... -.SH DESCRIPTION -asn1c compiles ASN.1 specifications into a set of -target language (C/C++) encoders and decoders for BER, DER, PER, XER -and other encoding rules. -.SH OPTIONS -.SS Stage Selection Options -.TP 4 -.B \-E -Run the parsing stage only. -Print the reconstructed ASN.1 text. -.TP 4 -.B \-F -Used together with -.B \-E\c -, instructs the compiler to stop after the ASN.1 syntax -tree fixing stage and dump the reconstructed ASN.1 specification -to the standard output. -.TP 4 -.B \-P -Dump the compiled output to the standard output instead of creating the -target language files on disk. -.TP 4 -.B \-R -Restrict the compiler to generate only the ASN.1 tables, -omitting the usual support code. -.TP 4 -\fB\-S\fR \fIdirectory\fR -Use the specified directory with ASN.1 skeleton files. -.TP 4 -.B \-X -Generate an XML DTD schema for the specified ASN.1 files. -.SS Warning Options -.TP 4 -.B \-Werror -Treat warnings as errors; abort if any warning is produced. -.TP 4 -.B \-Wdebug-lexer -Enable lexer debugging during the ASN.1 parsing stage. -.TP 4 -.B \-Wdebug-fixer -Enable ASN.1 syntax tree fixer debugging during the fixing stage. -.TP 4 -.B \-Wdebug-compiler -Enable debugging during the actual compile time. -.SS Language Options -.TP 4 -.B \-fbless-SIZE -Allow SIZE() constraint for INTEGER, ENUMERATED, and other types for which this -constraint is normally prohibited by the standard. -This is a violation of ASN.1 standard, and the compiler may -fail to\ produce a meaningful code. -.TP 4 -.B \-fcompound-names -Using this option prevents name collisions in the target source code -by using complex names for target language structures. -(Name\ collisions may occur if the ASN.1 module reuses the same identifiers -in multiple contexts). -.TP 4 -.B \-findirect-choice -When generating code for a CHOICE type, compile the CHOICE members as indirect -pointers instead of declaring them inline. -Consider using this option together with -.B \-fno-include-deps -to prevent circular references. -.TP 4 -.B \-fincludes-quoted -Generate #include lines in "double" instead of quotes. -.TP 4 -.BI "\-fknown-extern-type=" -Pretend the specified type is known. -The compiler will assume the target language source files -for the given type have been provided manually. -.TP 4 -.B \-fline-refs -Include ASN.1 module's line numbers in generated code comments. -.TP 4 -.B \-fno-constraints -Do not generate ASN.1 subtype constraint checking code. -This may make a shorter executable. -.TP 4 -.B \-fno-include-deps -Do not generate courtesy #include lines for non-critical type dependencies. -Helps prevent namespace collisions. -.TP 4 -.B \-funnamed-unions -Enable unnamed unions in the definitions of target language's structures. -.TP 4 -.B \-fwide-types -Use the unbounded size data types (INTEGER_t, ENUMERATED_t, REAL_t) by default, -instead of the native machine's data types (long, double). -.SS Codecs Generation Options -.TP 4 -.B \-gen-PER -Generate the Packed Encoding Rules (PER) support code. -.TP 4 -.B \-pdu=\fR{\fBall\fR|\fBauto\fR|\fIType\fR} -Create a PDU table for specified types, or discover Protocol Data Units automatically. -In case of -pdu=\fBall\fR, all ASN.1 types defined in all modules will form a PDU table. -In case of -pdu=\fBauto\fR, all types not referenced by any other type will form a PDU table. -If\ \fIType\fR is an ASN.1 type identifier, it is added to a PDU table. -The\ last form may be specified multiple times to add any number of PDUs. -.SS Output Options -.TP 4 -.B \-print-constraints -When -EF are also specified, this option forces the compiler to explain -its internal understanding of subtype constraints. -.TP 4 -.B \-print-lines -Generate "-- #line" comments in \fB-E\fR output. -.SH SEE ALSO -.TP 4 -\&\fIunber\fR\|(1), \&\fIenber\fR\|(1) -.SH AUTHORS -Lev Walkin diff --git a/asn1c/enber.1 b/asn1c/enber.1 deleted file mode 100644 index 999917eb..00000000 --- a/asn1c/enber.1 +++ /dev/null @@ -1,53 +0,0 @@ -.TH enber 1 "2014-10-23" "unber counterpart" -.if n .ad l \" Turn off justifications -.nh \" Turn off hyphenation; can damage formatting in technical documents. -.de Vb \" Verbatim begin. -.sp -.in +4 -.ft CW -.nf -.. -.de Ve \" Verbatim end. -.ft R -.in -.fi -.. -.SH NAME -enber \(em Convert the unber XML output back into BER -.SH SYNOPSIS -enber [\fB\-n\fR] [\fB\-\fR] [\fIinput-filenames\fR...] -.SH DESCRIPTION -enber convers the XML-formatted files produced by \fIunber\fR\|(1) back into the BER format. -A single dash denotes the standard input. -.SH OPTIONS -.TP 4 -\fB\-n\fR -Disable input validation. -By default, enber performs some basic validity checks -against XML input. -.SH EXAMPLES -Decode a BER sequence and immediately encode it back -.Vb -unber \fB\-p\fR \fIfilename.ber\fR | enber \fB\-\fR > \fIreconstructed.ber\fR -.Ve -.SH FOOTNOTES -This program does not attempt to perform full-fledged XML parsing. -It is merely compatible with \fIunber\fR\|(1)'s output. -In particular, XML style comments are not supported. -A hash "\fB#\fR" or two dashes "\fB--\fR" following a whitespace is treated as a beginning of a comment line, which is ignored completely. -Empty lines are ignored as well. -.P -The following example demostrates the use of comments: -.Vb - - - \fB--\fR - \fB#\fR Do not terminate: - \fB#\fR the absence of end-of-content octets is intentional! - -.Ve -.SH SEE ALSO -.TP -\fIunber\fR\|(1), \&\fIasn1c\fR\|(1) -.SH AUTHORS -Lev Walkin diff --git a/asn1c/unber.1 b/asn1c/unber.1 deleted file mode 100644 index e2725bd1..00000000 --- a/asn1c/unber.1 +++ /dev/null @@ -1,128 +0,0 @@ -.TH unber 1 "2014-10-23" "ASN.1 BER Decoder" -.if n .ad l \" Turn off justifications -.nh \" Turn off hyphenation; can damage formatting in technical documents. -.de Vb \" Verbatim. -.sp -.ft CW -.nf -.. -.de Vbi \" Verbatim, indented. -.sp -.ft CW -.nf -.in +4 -.. -.de Ve \" Verbatim end. -.ft R -.in -.fi -.sp -.. -.SH NAME -unber \(em the ASN.1 BER Decoder -.SH SYNOPSIS -unber [\fB\-1\fR] [\fB\-i\fRindent] [\fB\-m\fR] [\fB\-p\fR] [\fB\-s\fR\fIskip\fR] [\fB\-t\fR\fIhex\-string\fR] [\fB\-\fR] [\fIinput-filenames\fR...] -.SH DESCRIPTION -unber presents the internal structure of BER-encoded files as human readable text. -A single dash denotes the standard input. -.sp -(The DER and CER formats are subsets of the BER and are also supported.) -.SH OPTIONS -.TP -\fB\-1\fR -Do \fInot\fR attempt to read the next BER structure after the first one. -This may be useful if the input contains garbage past the single BER sequence. -By default, unber continues decoding until the end of file (input stream). -.TP -\fB\-i\fR \fIindent\fR -Use the specified number of spaces for output indentation. -Default is 4 spaces. -.TP -\fB\-m\fR -Generate shorter output while still preserving BER encoding information. -.TP -\fB\-p\fR -Do \fInot\fR attempt pretty-printing of known ASN.1 types (BOOLEAN, INTEGER, OBJECT IDENTIFIER, etc). -By default, some ASN.1 types are converted into the text representation. -This option is required for \&\fIenber\fR\|(1). -.TP -\fB\-s\fR \fIskip\fR -Ignore the first \fIskip\fR bytes in the input stream; useful for stripping off -lower level protocol framing data. -.TP -\fB\-t\fR \fIhex-string\fR -Interpret the hex-string as a sequence of hexadecimal values representing -the start of BER TLV encoding. -Print the human readable explanation. -.SH XML FORMAT -unber dumps the output in the regular XML format which preserves most of the -information from the underlying binary encoding. -.P -The XML opening tag format is as follows: -.Vb -<\fBtform\fR O="\fBoff\fR" T="\fBtag\fR" TL="\fBtl_len\fR" V="{Indefinite|\fBv_len\fR}" [A="\fBtype\fR"] [\fBF\fR]> -.Ve -Where: -.TP -\fBtform\fR -Encoding form the value is in: primitive ("P") or constructed ("C") or constructed with indefinite length ("I") -.TP -\fBoff\fR -Offset of the encoded element in the unber input stream. -.TP -\fBtag\fR -The tag class and value in human readable form. -.TP -\fBtl_len\fR -The length of the TL (BER Tag and Length) encoding. -.TP -\fBv_len\fR -The length of the value (V, encoded by the L), may be "Indefinite". -.TP -\fBtype\fR -Likely name of the underlying ASN.1 type (for UNIVERSAL tags). -.TP -[\fBF\fR] -Indicates that the value was reformatted (pretty-printed). -This will never appear in the output produced using \fB\-p\fR command line option. -.P -Sample XML output: -.Vb - -

US

- -

832970823

- - -.Ve -.SH EXAMPLES -Decode the given Tag/Length sequence specified in hexadecimal form: -.Vbi -unber \fB\-t\fR "\fIbf 20\fR" -.Ve -Decode the DER file using two-spaces indentation: -.Vbi -unber \fB\-i\fR \fI2\fR \fIfilename.der\fR -.Ve -Decode the binary stream taken from the standard input: -.Vbi -cat \fIfilename.der\fR | unber \fB\-\fR -.Ve -Decode the binary stream and encode it back into an identical stream (see \&\fIenber\fR\|(1)): -.Vbi -cat \fIfilename.der\fR | unber \fB\-p\fR \fB\-\fR | enber \fB\-\fR > \fIfilename.ber\fR -.Ve -.SH FOOTNOTES -The constructed XML output is not necessarily well-formed. -.P -When indefinite length encoding is being used, the BER sequence, which is not -terminated with the end-of-content octets, will cause the terminating \fB\fR -XML tag to disappear. -Thus, invalid BER framing directly causes invalid XML output. -.P -The \fIenber\fR\|(1) utility understands such XML correctly. -.SH SEE ALSO -.TP -\fIenber\fR\|(1), \fIasn1c\fR\|(1) -.SH AUTHORS -Lev Walkin diff --git a/configure.ac b/configure.ac index 2698265a..478e0fe5 100644 --- a/configure.ac +++ b/configure.ac @@ -111,6 +111,10 @@ AC_CHECK_FUNCS(timegm) AC_CHECK_DECLS(alloca strcasecmp) AC_TRY_LINK_FUNC([symlink],[AC_DEFINE([HAVE_SYMLINK], 1, [Define to 1 if you have the symlink function.])]) +dnl Use pandoc to generate manual pages. +AC_PATH_PROG([PANDOC], pandoc) +AM_CONDITIONAL([HAVE_PANDOC], [test -n "$PANDOC"]) + AC_OUTPUT( \ skeletons/tests/Makefile \ libasn1compiler/Makefile \ @@ -121,6 +125,7 @@ libasn1fix/Makefile \ doc/docsrc/Makefile \ skeletons/Makefile \ examples/Makefile \ +doc/man/Makefile \ asn1c/Makefile \ doc/Makefile \ asn1c.spec \ diff --git a/doc/Makefile.am b/doc/Makefile.am index 9582917c..aa462b7d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,5 +1,5 @@ -SUBDIRS = docsrc +SUBDIRS = docsrc man docsdir = $(datadir)/doc/asn1c diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am new file mode 100644 index 00000000..1035ff96 --- /dev/null +++ b/doc/man/Makefile.am @@ -0,0 +1,16 @@ + +dist_man1_MANS = asn1c.1 unber.1 enber.1 + +if HAVE_PANDOC + +PANDOC_OPTIONS= --from markdown --to man \ + --variable header="Version ${VERSION}" \ + --variable adjusting:l \ + --variable hyphenate:"" \ + --standalone + +%.1: %.man.md + ${PANDOC} ${PANDOC_OPTIONS} -o $@ $< + +endif + diff --git a/doc/man/asn1c.1 b/doc/man/asn1c.1 new file mode 100644 index 00000000..54c23373 --- /dev/null +++ b/doc/man/asn1c.1 @@ -0,0 +1,199 @@ +.\" Automatically generated by Pandoc 1.16.0.2 +.\" +.ad l +.TH "asn1c" "1" "2016\-01\-23" "ASN.1 Compiler" "Version 0.9.28" +.nh \" Turn off hyphenation by default. +.SH NAME +.PP +asn1c \-\- the ASN.1 Compiler +.SH SYNOPSIS +.PP +asn1c [\f[B]\-E\f[] [\f[B]\-F\f[]] | \f[B]\-P\f[] | \f[B]\-R\f[]] +.PD 0 +.P +.PD +[\f[B]\-S\f[]\f[I]dir\f[]] [\f[B]\-X\f[]] +.PD 0 +.P +.PD +[\f[B]\-W\f[]\f[I]debug\-\f[]...] [\f[B]\-f\f[]\f[I]option\f[]] +[\f[B]\-gen\-\f[]\f[I]option\f[]] +[\f[B]\-pdu\f[]={\f[B]all\f[]|\f[B]auto\f[]|\f[I]Type\f[]}] +.PD 0 +.P +.PD +[\f[B]\-print\-\f[]\f[I]option\f[]] +.PD 0 +.P +.PD +\f[I]input\-filenames\f[]... +.SH DESCRIPTION +.PP +asn1c compiles ASN.1 specifications into a set of target language +(C/C++) encoders and decoders for BER, DER, PER, XER and other encoding +rules. +.SH OPTIONS +.SS Stage Selection Options +.TP +.B \-E +Run the parsing stage only. +Print the reconstructed ASN.1 text. +.RS +.RE +.TP +.B \-F +Used together with \f[B]\-E\f[], instructs the compiler to stop after +the ASN.1 syntax tree fixing stage and dump the reconstructed ASN.1 +specification to the standard output. +.RS +.RE +.TP +.B \-P +Dump the compiled output to the standard output instead of creating the +target language files on disk. +.RS +.RE +.TP +.B \-R +Restrict the compiler to generate only the ASN.1 tables, omitting the +usual support code. +.RS +.RE +.TP +.B \-S \f[I]directory\f[] +Use the specified directory with ASN.1 skeleton files. +.RS +.RE +.TP +.B \-X +Generate an XML DTD schema for the specified ASN.1 files. +.RS +.RE +.SS Warning Options +.TP +.B \-Werror +Treat warnings as errors; abort if any warning is produced. +.RS +.RE +.TP +.B \-Wdebug\-lexer +Enable lexer debugging during the ASN.1 parsing stage. +.RS +.RE +.TP +.B \-Wdebug\-fixer +Enable ASN.1 syntax tree fixer debugging during the fixing stage. +.RS +.RE +.TP +.B \-Wdebug\-compiler +Enable debugging during the actual compile time. +.RS +.RE +.SS Language Options +.TP +.B \-fbless\-SIZE +Allow \f[C]SIZE()\f[] constraint for \f[C]INTEGER\f[], +\f[C]ENUMERATED\f[], and other types for which this constraint is +normally prohibited by the standard. +This is a violation of ASN.1 standard, and the compiler may fail to +produce a meaningful code. +.RS +.RE +.TP +.B \-fcompound\-names +Using this option prevents name collisions in the target source code by +using complex names for target language structures. +(Name collisions may occur if the ASN.1 module reuses the same +identifiers in multiple contexts). +.RS +.RE +.TP +.B \-findirect\-choice +When generating code for a \f[C]CHOICE\f[] type, compile the +\f[C]CHOICE\f[] members as indirect pointers instead of declaring them +inline. +Consider using this option together with \f[B]\-fno\-include\-deps\f[] +to prevent circular references. +.RS +.RE +.TP +.B \-fincludes\-quoted +Refer to header files in \f[C]#include\f[]s using +\f[B]"\f[]double\f[B]"\f[] instead of \f[B]<\f[]angle\f[B]>\f[] quotes. +.RS +.RE +.TP +.B \-fknown\-extern\-type=\f[I]name\f[] +Pretend the specified type is known. +The compiler will assume the target language source files for the given +type have been provided manually. +.RS +.RE +.TP +.B \-fline\-refs +Include ASN.1 module\[aq]s line numbers in generated code comments. +.RS +.RE +.TP +.B \-fno\-constraints +Do not generate ASN.1 subtype constraint checking code. +This may make a shorter executable. +.RS +.RE +.TP +.B \-fno\-include\-deps +Do not generate courtesy #include lines for non\-critical type +dependencies. +Helps prevent namespace collisions. +.RS +.RE +.TP +.B \-funnamed\-unions +Enable unnamed unions in the definitions of target language\[aq]s +structures. +.RS +.RE +.TP +.B \-fwide\-types +Use the unbounded size data types (\f[C]INTEGER_t\f[], +\f[C]ENUMERATED_t\f[], \f[C]REAL_t\f[]) by default, instead of using the +native machine\[aq]s data types (long, double). +.RS +.RE +.SS Codecs Generation Options +.TP +.B \-gen\-PER +Generate the Packed Encoding Rules (PER) support code. +.RS +.RE +.TP +.B \-pdu={all|auto|\f[I]Type\f[]} +Create a PDU table for specified types, or discover Protocol Data Units +automatically. +In case of \f[B]\-pdu=all\f[], all ASN.1 types defined in all modules +will form a PDU table. +In case of \f[B]\-pdu=auto\f[], all types not referenced by any other +type will form a PDU table. +If \f[I]Type\f[] is an ASN.1 type identifier, the identifier is added to +the generated PDU table. +The last form may be specified multiple times to add any number of PDUs. +.RS +.RE +.SS Output Options +.TP +.B \-print\-constraints +When \f[B]\-EF\f[] options are also specified, this option forces the +compiler to explain its internal understanding of subtype constraints. +.RS +.RE +.TP +.B \-print\-lines +Generate "\f[C]\-\-\ #line\f[]" comments in \f[B]\-E\f[] output. +.RS +.RE +.SH SEE ALSO +.PP +\f[C]unber\f[](1), \f[C]enber\f[](1). +.SH AUTHORS +Lev Walkin . diff --git a/doc/man/asn1c.man.md b/doc/man/asn1c.man.md new file mode 100644 index 00000000..afec71f9 --- /dev/null +++ b/doc/man/asn1c.man.md @@ -0,0 +1,140 @@ +% asn1c(1) ASN.1 Compiler +% Lev Walkin +% 2016-01-23 + +# NAME + +asn1c -- the ASN.1 Compiler + +# SYNOPSIS + +asn1c [**-E** [**-F**] | **-P** | **-R**] \ + [**-S***dir*] [**-X**] \ + [**-W***debug-*...] [**-f***option*] [**-gen-***option*] + [**-pdu**={**all**|**auto**|*Type*}] \ + [**-print-***option*] \ + *input-filenames*... + +# DESCRIPTION + +asn1c compiles ASN.1 specifications into a set of +target language (C/C++) encoders and decoders for BER, DER, PER, XER +and other encoding rules. + +# OPTIONS + +## Stage Selection Options + +-E +: Run the parsing stage only. Print the reconstructed ASN.1 text. + +-F +: Used together with **-E**, + instructs the compiler to stop after the ASN.1 syntax + tree fixing stage and dump the reconstructed ASN.1 specification + to the standard output. + +-P +: Dump the compiled output to the standard output instead of creating the + target language files on disk. + +-R +: Restrict the compiler to generate only the ASN.1 tables, + omitting the usual support code. + +-S *directory* +: Use the specified directory with ASN.1 skeleton files. + +-X +: Generate an XML DTD schema for the specified ASN.1 files. + +## Warning Options + +-Werror +: Treat warnings as errors; abort if any warning is produced. + +-Wdebug-lexer +: Enable lexer debugging during the ASN.1 parsing stage. + +-Wdebug-fixer +: Enable ASN.1 syntax tree fixer debugging during the fixing stage. + +-Wdebug-compiler +: Enable debugging during the actual compile time. + +## Language Options + +-fbless-SIZE +: Allow `SIZE()` constraint for `INTEGER`, `ENUMERATED`, + and other types for which this constraint is normally prohibited + by the standard. + This is a violation of ASN.1 standard, and the compiler may + fail to produce a meaningful code. + +-fcompound-names +: Using this option prevents name collisions in the target source code + by using complex names for target language structures. + (Name collisions may occur if the ASN.1 module reuses the same identifiers + in multiple contexts). + +-findirect-choice +: When generating code for a `CHOICE` type, compile the `CHOICE` members + as indirect pointers instead of declaring them inline. + Consider using this option together with **-fno-include-deps** + to prevent circular references. + +-fincludes-quoted +: Refer to header files in `#include`s using **"**double**"** instead of **\<**angle**>** quotes. + +-fknown-extern-type=*name* +: Pretend the specified type is known. + The compiler will assume the target language source files + for the given type have been provided manually. + +-fline-refs +: Include ASN.1 module's line numbers in generated code comments. + +-fno-constraints +: Do not generate ASN.1 subtype constraint checking code. + This may make a shorter executable. + +-fno-include-deps +: Do not generate courtesy #include lines for non-critical type dependencies. + Helps prevent namespace collisions. + +-funnamed-unions +: Enable unnamed unions in the definitions of target language's structures. + +-fwide-types +: Use the unbounded size data types (`INTEGER_t`, `ENUMERATED_t`, `REAL_t`) + by default, instead of using the native machine's data types (long, double). + +## Codecs Generation Options + +-gen-PER +: Generate the Packed Encoding Rules (PER) support code. + +-pdu={all|auto|*Type*} +: Create a PDU table for specified types, or discover Protocol Data Units + automatically. In case of **-pdu=all**, + all ASN.1 types defined in all modules will form a PDU table. + In case of **-pdu=auto**, all types not referenced by any other type will + form a PDU table. + If *Type* is an ASN.1 type identifier, the identifier is added to + the generated PDU table. + The last form may be specified multiple times to add any number of PDUs. + +## Output Options + +-print-constraints +: When **-EF** options are also specified, + this option forces the compiler to explain its internal understanding + of subtype constraints. + +-print-lines +: Generate "`-- #line`" comments in **-E** output. + +# SEE ALSO + +`unber`(1), `enber`(1). + diff --git a/doc/man/enber.1 b/doc/man/enber.1 new file mode 100644 index 00000000..827c211b --- /dev/null +++ b/doc/man/enber.1 @@ -0,0 +1,71 @@ +.\" Automatically generated by Pandoc 1.16.0.2 +.\" +.ad l +.TH "enber" "1" "2016\-01\-23" "unber(1) counterpart" "Version 0.9.28" +.nh \" Turn off hyphenation by default. +.SH NAME +.PP +enber \-\- Convert the unber XML output back into BER +.SH SYNOPSIS +.PP +enber [\f[B]\-n\f[]] [\f[B]\-\f[]] [\f[I]input\-filenames\f[]...] +.SH DESCRIPTION +.PP +enber converts the XML\-formatted files produced by \f[C]unber\f[](1) +back into the BER format. +A single dash denotes the standard input. +.SH OPTIONS +.TP +.B \-n +Disable input validation. +By default, enber performs some basic validity checks against XML input. +.RS +.RE +.SH EXAMPLES +.PP +Decode a BER sequence and immediately encode it back +.RS +.PP +unber \f[B]\-p\f[] \f[I]filename.ber\f[] | enber \f[B]\-\f[] > +\f[I]reconstructed.ber\f[] +.RE +.SH FOOTNOTES +.PP +This program does not attempt to perform full\-fledged XML parsing. +It is merely compatible with \f[C]unber\f[](1)\[aq]s output. +In particular, the XML style comments are not supported. +A hash "\f[B]#\f[]" or two dashes "\f[B]\-\-\f[]" following a whitespace +is treated as a beginning of a comment line, which is ignored +completely. +Empty lines are ignored as well. +.PP +The following example \f[C]enber\f[](1) input demostrates the use of +comments: +.PP + +.PD 0 +.P +.PD +\ \ \ \ +.PD 0 +.P +.PD +\ \ \ \ \f[B]\-\-\f[] +.PD 0 +.P +.PD +\ \ \ \ \f[B]#\f[] Do not terminate: +.PD 0 +.P +.PD +\ \ \ \ \f[B]#\f[] the absence of end\-of\-content octets is +intentional! +.PD 0 +.P +.PD + +.SH SEE ALSO +.PP +\f[C]unber\f[](1), \f[C]asn1c\f[](1). +.SH AUTHORS +Lev Walkin . diff --git a/doc/man/enber.man.md b/doc/man/enber.man.md new file mode 100644 index 00000000..2bdb0369 --- /dev/null +++ b/doc/man/enber.man.md @@ -0,0 +1,50 @@ +% enber(1) unber(1) counterpart +% Lev Walkin +% 2016-01-23 + +# NAME + +enber -- Convert the unber XML output back into BER + +# SYNOPSIS + +enber [**-n**] [**-**] [*input-filenames*...] + +# DESCRIPTION + +enber converts the XML-formatted files produced by `unber`(1) back into the BER format. +A single dash denotes the standard input. + +# OPTIONS + +-n +: Disable input validation. +By default, enber performs some basic validity checks +against XML input. + +# EXAMPLES + +Decode a BER sequence and immediately encode it back + +> unber **-p** *filename.ber* | enber **-** > *reconstructed.ber* + +# FOOTNOTES + +This program does not attempt to perform full-fledged XML parsing. +It is merely compatible with `unber`(1)'s output. +In particular, the XML style comments are not supported. +A hash "**#**" or two dashes "**--**" following a whitespace is treated as a beginning of a comment line, which is ignored completely. +Empty lines are ignored as well. + +The following example `enber`(1) input demostrates the use of comments: + +| \ +| \ +| **--** \ +| **#** Do not terminate: +| **#** the absence of end-of-content octets is intentional! +| \ + +# SEE ALSO + +`unber`(1), `asn1c`(1). diff --git a/doc/man/unber.1 b/doc/man/unber.1 new file mode 100644 index 00000000..8f787b40 --- /dev/null +++ b/doc/man/unber.1 @@ -0,0 +1,181 @@ +.\" Automatically generated by Pandoc 1.16.0.2 +.\" +.ad l +.TH "unber" "1" "2016\-01\-23" "ASN.1 BER Decoder" "Version 0.9.28" +.nh \" Turn off hyphenation by default. +.SH NAME +.PP +unber \-\- the ASN.1 BER Decoder +.SH SYNOPSIS +.PP +unber [\f[B]\-1\f[]] [\f[B]\-i\f[]\f[I]indent\f[]] [\f[B]\-m\f[]] +[\f[B]\-p\f[]] [\f[B]\-s\f[]\f[I]skip\f[]] +[\f[B]\-t\f[]\f[I]hex\-string\f[]] [\f[B]\-\f[]] +[\f[I]input\-filenames\f[]...] +.SH DESCRIPTION +.PP +unber presents the internal structure of BER\-encoded files as a human +readable text. +A single dash denotes the standard input. +.PP +(The DER and CER formats are subsets of the BER and are also supported.) +.SH OPTIONS +.TP +.B \-1 +Do \f[I]not\f[] attempt to read the next BER structure after the first +one. +This may be useful if the input contains garbage past the single BER +sequence. +By default, unber continues decoding until the end of file (input +stream). +.RS +.RE +.TP +.B \-i \f[I]indent\f[] +Use the specified number of spaces for output indentation. +Default is 4 spaces. +.RS +.RE +.TP +.B \-m +Generate shorter output while still preserving BER encoding information. +.RS +.RE +.TP +.B \-p +Do \f[I]not\f[] attempt to pretty\-print known ASN.1 types +(\f[C]BOOLEAN\f[], \f[C]INTEGER\f[], \f[C]OBJECT\ IDENTIFIER\f[], etc). +By default, some ASN.1 types are converted into the text representation. +.RS +.PP +This option is required if the \f[C]unber\f[](1) output is used as an +input to \f[C]enber\f[](1). +.RE +.TP +.B \-s \f[I]skip\f[] +Ignore the first \f[I]skip\f[] bytes in the input stream; useful for +stripping off lower level protocol framing data. +.RS +.RE +.TP +.B \-t \f[I]hex\-string\f[] +Interpret the hex\-string as a sequence of hexadecimal values +representing the start of BER TLV encoding. +Print the human readable explanation. +.RS +.RE +.SH XML FORMAT +.PP +unber dumps the output in the regular XML format which preserves most of +the information from the underlying binary encoding. +.PP +The XML opening tag format is as follows: +.PP +<\f[B]tform\f[] O="\f[B]off\f[]" T="\f[B]tag\f[]" TL="\f[B]t_len\f[]" +V="{Indefinite|\f[B]v_len\f[]}" [A="\f[B]type\f[]"] [\f[B]F\f[]]> +.PP +Where: +.TP +.B \f[B]tform\f[] +Encoding form the value is in: primitive ("P") or constructed ("C") or +constructed with indefinite length ("I") +.RS +.RE +.TP +.B \f[B]off\f[] +Offset of the encoded element in the unber input stream. +.RS +.RE +.TP +.B \f[B]tag\f[] +The tag class and value in human readable form. +.RS +.RE +.TP +.B \f[B]t_len\f[] +The length of the TL (BER Tag and Length) encoding. +.RS +.RE +.TP +.B \f[B]v_len\f[] +The length of the value (V, encoded by the L), may be "Indefinite". +.RS +.RE +.TP +.B \f[B]type\f[] +Likely name of the underlying ASN.1 type (for UNIVERSAL tags). +.RS +.RE +.TP +.B [\f[B]F\f[]] +Indicates that the value was reformatted (pretty\-printed). +This will never appear in the output produced using the \f[B]\-p\f[] +command line option. +.RS +.RE +.SS Example XML output: +.PP + +.PD 0 +.P +.PD +\

US

+.PD 0 +.P +.PD +\ \ +.PD 0 +.P +.PD +\ \ \ \

832970823

+.PD 0 +.P +.PD +\ \ +.PD 0 +.P +.PD + +.SH EXAMPLES +.PP +Decode the given Tag/Length sequence specified in hexadecimal form: +.RS +.PP +unber\ \f[B]\-t\f[] "\f[I]bf 20\f[]" +.RE +.PP +Decode the DER file using two\-spaces indentation: +.RS +.PP +unber\ \f[B]\-i\f[] \f[I]2\f[]\ \f[I]filename.der\f[] +.RE +.PP +Decode the binary stream taken from the standard input: +.RS +.PP +cat \f[I]filename.der\f[] | unber \f[B]\-\f[] +.RE +.PP +Decode the binary stream and encode it back into an identical stream +(see \f[C]enber\f[](1)): +.RS +.PP +cat \f[I]filename.der\f[] | unber \f[B]\-p\f[] \f[B]\-\f[] | enber +\f[B]\-\f[] > \f[I]filename.ber\f[] +.RE +.SH FOOTNOTES +.PP +The constructed XML output is not necessarily well\-formed. +.PP +When indefinite length encoding is being used, the BER sequence which is +not terminated with the end\-of\-content octets will cause the +terminating \f[B]\f[] XML tag to disappear. +Thus, invalid BER framing directly causes invalid XML output. +.PP +The \f[C]enber\f[](1) utility understands such XML correctly. +.SH SEE ALSO +.PP +\f[C]enber\f[](1), \f[C]asn1c\f[](1). +.SH AUTHORS +Lev Walkin . diff --git a/doc/man/unber.man.md b/doc/man/unber.man.md new file mode 100644 index 00000000..b110eb86 --- /dev/null +++ b/doc/man/unber.man.md @@ -0,0 +1,121 @@ +% unber(1) ASN.1 BER Decoder +% Lev Walkin +% 2016-01-23 + +# NAME + +unber -- the ASN.1 BER Decoder + +# SYNOPSIS + +unber [**-1**] [**-i***indent*] [**-m**] [**-p**] [**-s***skip*] [**-t***hex-string*] [**-**] [*input-filenames*...] + +# DESCRIPTION + +unber presents the internal structure of BER-encoded files as a human readable text. +A single dash denotes the standard input. + +(The DER and CER formats are subsets of the BER and are also supported.) + +# OPTIONS + +-1 +: Do *not* attempt to read the next BER structure after the first one. + This may be useful if the input contains garbage past the single BER sequence. + By default, unber continues decoding until the end of file (input stream). + +-i *indent* +: Use the specified number of spaces for output indentation. + Default is 4 spaces. + +-m +: Generate shorter output while still preserving BER encoding information. + +-p +: Do *not* attempt to pretty-print known ASN.1 types (`BOOLEAN`, `INTEGER`, `OBJECT IDENTIFIER`, etc). + By default, some ASN.1 types are converted into the text representation. + + This option is required if the `unber`(1) output is used as an input to `enber`(1). + +-s *skip* +: Ignore the first *skip* bytes in the input stream; + useful for stripping off lower level protocol framing data. + +-t *hex-string* +: Interpret the hex-string as a sequence of hexadecimal values representing + the start of BER TLV encoding. + Print the human readable explanation. + +# XML FORMAT +unber dumps the output in the regular XML format which preserves most of the +information from the underlying binary encoding. + +The XML opening tag format is as follows: + +<**tform** O="**off**" T="**tag**" TL="**t_len**" V="{Indefinite|**v_len**}" [A="**type**"] [**F**]> + +Where: + +**tform** +: Encoding form the value is in: primitive ("P") or constructed ("C") or constructed with indefinite length ("I") + +**off** +: Offset of the encoded element in the unber input stream. + +**tag** +: The tag class and value in human readable form. + +**t_len** +: The length of the TL (BER Tag and Length) encoding. + +**v_len** +: The length of the value (V, encoded by the L), may be "Indefinite". + +**type** +: Likely name of the underlying ASN.1 type (for UNIVERSAL tags). + +[**F**] +: Indicates that the value was reformatted (pretty-printed). +This will never appear in the output produced using the **-p** +command line option. + +## Example XML output: + +| \ +| \

US\

+| \ +| \

832970823\

+| \ +| \ + +# EXAMPLES + +Decode the given Tag/Length sequence specified in hexadecimal form: + +> unber\ **-t** "*bf 20*" + +Decode the DER file using two-spaces indentation: + +> unber\ **-i** *2*\ *filename.der* + +Decode the binary stream taken from the standard input: + +> cat *filename.der* | unber **-** + +Decode the binary stream and encode it back into an identical stream (see `enber`(1)): + +> cat *filename.der* | unber **-p** **-** | enber **-** > *filename.ber* + +# FOOTNOTES +The constructed XML output is not necessarily well-formed. + +When indefinite length encoding is being used, the BER sequence which is not +terminated with the end-of-content octets will cause the terminating **\** +XML tag to disappear. +Thus, invalid BER framing directly causes invalid XML output. + +The `enber`(1) utility understands such XML correctly. + +# SEE ALSO + +`enber`(1), `asn1c`(1).