From ded34c5f5963487db6a9ea2158508ee5a77915ad Mon Sep 17 00:00:00 2001 From: Paul Meyer <49727155+katexochen@users.noreply.github.com> Date: Mon, 31 Jul 2023 08:23:11 +0200 Subject: [PATCH] Add readme Signed-off-by: Paul Meyer <49727155+katexochen@users.noreply.github.com> --- README.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/README.md b/README.md index e69de29..c057d77 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,108 @@ +# `dumpasn1` - display and debug ASN.1 data + +> [!NOTE]\ +> Copyright Peter Gutmann + +This is a mirror of Peter Gutmann's `dumpasn1`, adding versioning of both code and config +and automated updates from upstream. + +## About + +`dumpasn1` is an ASN.1 object dump program that will dump data encoded using any of the ASN.1 encoding +rules in a variety of user-specified formats. Sample output from this program (using the default format) is: + +``` + 256 159: SEQUENCE { + 259 13: SEQUENCE { + 261 9: OBJECT IDENTIFIER rsaEncryption (1 2 840 113549 1 1 1) + 272 0: NULL + : } + 274 141: BIT STRING, encapsulates { + 278 137: SEQUENCE { + 281 129: INTEGER + : 00 E5 19 BF 6D A3 56 61 2D 99 48 71 F6 67 DE B9 +[...] : 8F + 413 3: INTEGER 65537 + : } + : } + : } +``` + +## Usage + +``` +DumpASN1 - ASN.1 object dump/syntax check program. +Copyright Peter Gutmann 1997 - 2021. Last updated 22 April 2021. + +Usage: dumpasn1 [-acdefghilmopqrstuvwxz] + Input options: + - = Take input from stdin (some display options will be disabled) + -q = Disable warning about stdin use affecting display options + - = Start bytes into the file + -- = End of arg list + -c = Read Object Identifier info from alternate config file + (values will override equivalents in global config file) + + Output options: + -f = Dump object at offset - to file (allows data to be + extracted from encapsulating objects) + -w = Set width of output, default = 80 columns + + Display options: + -a = Print all data in long data blocks, not just the first 128 bytes + -d = Print dots to show column alignment + -g = Display ASN.1 structure outline only (no primitive objects) + -h = Hex dump object header (tag+length) before the decoded output + -hh = Same as -h but display more of the object as hex data + -i = Use shallow indenting, for deeply-nested objects + -l = Long format, display extra info about Object Identifiers + -m = Maximum nesting level for which to display content + -p = Pure ASN.1 output without encoding information + -t = Display text values next to hex dump of data + -v = Verbose mode, equivalent to -ahlt + + Format options: + -e = Don't print encapsulated data inside OCTET/BIT STRINGs + -r = Print bits in BIT STRING as encoded in reverse order + -u = Don't format UTCTime/GeneralizedTime string data + -x = Display size and offset in hex not decimal + + Checking options: + -o = Don't check validity of character strings hidden in octet strings + -s = Syntax check only, don't dump ASN.1 structures + -z = Allow zero-length items + +Warnings generated by deprecated OIDs require the use of '-l' to be displayed. +Program return code is the number of errors found or EXIT_SUCCESS. +``` + +The expected input format is DER (binary). If your certificate is PEM encoded (with `—–BEGIN CERTIFICATE—–`), +you can convert it, e.g., with openssl: + +```sh +openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER +``` + +## Versioning + +This code uses the date versioning available in the upstream code and adds Git tags and releases +accordingly. Upstream, source and config are versioned independent of each other. Whenever one or +the other is updated, this repo is tagged with the date version of format that is stated in +the source, and a new release is added. The version from the file, which has the format `YYYYMMDD` +is transformed into a semantic version of the form `vYYYYMMDD.%d.%d` (e.g., `v20230207.0.0`), where +the minor and patch versions are controlled by this repository. To further track the different versions +of config and code, additional tags are added specific to either code or config: `YYMMDD-c` for the +latest code version, and `YYYYMMDD-cfg` for the latest config version. + +## License + +For easier redistribution, the code is re-licensed with a BSD 2-Clause license, which should +be compatible to the original non-standard license you find in the header comment of the C source as well +as the config. Notice that the original license is more permissive than one the present in the LICENSE file of +this repository, so you can always follow the original license of the source if you prefer to. + +## Related + +- [Peter Gutmann's website](https://www.cs.auckland.ac.nz/~pgut001/#standards) has more information on `dumpasn1`, + security standards and an X.509 style guide. +- [ASN.1 online decoder](http://lapo.it/asn1js/) provides a nice interface to debug your ASN.1 in browser.