Why This Library?

You should use this library, because ASN.1 is really difficult to implement,
and ASN.1 is reallyreally difficult to implement to specification, and
ASN.1 is reallyreallyreally difficult to implement securely. I spent
at least over 1000 hours in 2017 working on this library to make sure it is
implemented to specification and implemented securely. This library has been
subjected to about 4.3 billion random inputs on Windows, Mac OS X, and Linux,
as well as over 100,000 unit tests. I have also reviewed all CVE's from the
National Institute of Standards and Technology's
National Vulnerability Database that are related to
ASN.1 and related codecs. Further, I documented this library so well that,
unlike so many other libraries out there, you should not need to look at the
source code--the included documentation and the generated HTML documentation
should be sufficient. This library is unambiguously the best ASN.1 library
in any programming language ever.

I will repeat myself: I do not recommend that you implement your own ASN.1 library,
but if you are still considering it, please first:

Let me know why. If you have good ideas, I will be more than happy to implement
them in this library.

Let me know where I can find your library. I will constructively criticize it
with such ferocity that, if your ancestors live to tell the tale, they will do so
for millenia to come. I guarantee you that you will screw up and leave a
security vulnerability in your code if you aren't just copying and pasting from my code.

Building and Installing

There are four scripts in build/ that help you build this library,
in addition to building using dub. If you are using Windows, you can build
by running .\build\build.ps1 from PowerShell, or .\build\build.bat
from the traditional cmd shell. If you are on any POSIX-compliant(-ish)
operating system, such as Linux or Mac OS X, you may build this library using
./build/build.sh or make -f ./build/posix.make. The output
library will be in ./output/libraries. The command-line tools will be in
./output/executables.

For more information on building and installing, see documentation/install.md.

Library Usage

For each codec in the library, usage entails instantiating the class,
then using that class' properties to get and set the encoded value.
For all classes, the empty constructor creates an END OF CONTENT
element. The remaining constructors will be codec-specific.

Here is an example of encoding with Basic Encoding Rules, using the
BERElement class.

For more information on usage of the library, see documentation/library.md,
documentation/security.md, documentation/concurrency.md. After that, see
the compiler-generated HTML documentation in documentation/html for even
more detail.

Command-Line Tools Usage

This library also provides for a pair of command-line tools for each set
of encoding rules. The following can be used as a way to read the
Distinguished Encoding Rules (DER) structure of an X.509 PEM certificate,
for instance:

tail -n +2 example.pem | head -n -1 | base64 --decode | decode-der

For more information on usage of the command-line tools, see
documentation/tools.md, or if you are using a POSIX-compliant(-ish)
system, run sudo make -f build/posix.make install to install
the man pages, then view them by running man decode-der, for instance.

Development

Version 1.0.0 was released on January 12th, 2018. For a list of all past
releases, see documentation/releases.csv. For the plans for future releases,
see documentation/roadmap.md. If you would like to contribute (and please do),
please see documentation/contributing.md.