Jason
=====

A JSON to ASN.1/DER encoder/decoder, in C.

The `libjason` library is able to parse JSON, and encode it to ASN.1
using the Distinguished Encoding Rules (DER) of ITU-T X.690.

The library parses JSON as specified in [RFC 4627][], with no
extensions.  However the string parser cannot at present handle
Unicode strings (which also means it doesn't respect the JSON `\uXXXX`
escape); all strings must be ASCII. 

The DER *de*coder can handle some BER-encoded objects, but not all,
and it doesn't attempt to handle ASN.1 types other than the subset
which it generates.

In this encoding, JSON integers, floats, booleans, and null, are
encoded to the DER analogues.  A JSON array is encoded to a DER
`SEQUENCE`, an object to a `SET OF` two-element sequences, and strings
to DER `ia5string` objects (the `ia5string` restriction is because this
parser currently handles only ASCII).

This may or may not be the best way to approach this problem.  There
is an interesting comparison of approaches discussed in [RFC 7049][],
which describes an alternative called _Concise Binary Object
Representation_ (CBOR).

DER is specified in ITU-T Rec. X.690, as part of the ASN/1 suite of
standards.  See the [ITU-T recommendation][] and [Wikipedia][], and
Burton S. Kaliski Jr., *A Layman's Guide to a Subset of ASN.1, BER,
and DER* (1993).


Building
--------

Building from a distribution:

    ./configure
    make
    make check

If building from the repository, then this build sequence must be
preceded by `./bootstrap`, and the GNU autotools must be installed.

The build depends on `flex` and `bison` being in the path.
There are no other dependencies.


Utility program
---------------

As well as a library (documented below), this kit includes a program
`json2der` which encodes and decodes JSON to DER on the command-line.
See the man-page `json2der.1` for details.


Interface
---------

The interface is still somewhat preliminary, and not documented very
elaborately.  However...

Unless noted otherwise, each of the non-void functions returns an
object which is owned by the caller, which must subsequently free it
either with `jason_free_object()` or plain `free()`.

The exceptions are functions `jason_get_...`.
Each of these returns a pointer to an object which is either static or
(in the case of `jason_get_der_encoding`) object by another object.

    #include <jason.h>

    JsonObject jason_parse_string(const char* json_string);

Parse the JSON object given in the string.  If the string cannot be
parsed, then this returns `NULL`, and an explanation is available from
the function `const char* jason_get_error_message()`.

    JsonObject jason_parse_der_bytes(uint8_t*, size_t, size_t*);

Decode a sequence of bytes which are the DER encoding of a JSON
object, and return the object.  If the byte sequence
cannot be parsed, then this returns `NULL`, and an explanation is
available from the function `const char* jason_get_error_message()`.

A `JsonObject` should be freed by `jason_free_object` when no longer required.  

    void jason_free_object(JsonObject o);

Free the object.  Any allocated memory within the object is freed also.

    const char* jason_get_error_message(void);

Retrieve the error message associated with a recent JSON parse, or DER
encoding.  This string must not be freed.

    const char* jason_print_object(JsonObject obj);

Serialise the object to a string.

    uint8_t* jason_get_der_encoding(JsonObject obj, size_t *len);

Get the DER-encoding of the object.
The object must not be freed by the caller.

    char* jason_bytes_to_string(uint8_t* b, size_t blen);

Utility method to serialise a byte sequence to a printable string of
hex digits.

    const char* jason_get_version_string(void);
    int jason_version_number(void);

Return information about the library version number.  The
value returned by `jason_get_version_string` must not be freed.

The contents of the `JsonObject` structure should be fairly stable.
See the `jason.h` header for the details.


Name
----

The name *Jason* is a fairly obvious amalgam of JSON and ASN.
JASN would be a better name,
but [that name's already taken][jasn] for a Java ASN parser.


Source code and licence information
-----------------------------------

The source code is available at <https://bitbucket.org/nxg/jason>.

Jason is Copyright 2013, 2014 Norman Gray, and is released under the
terms of the [BSD 2-clause licence][] (see the file LICENCE for text).

The distribution includes the [`lcut` unit-testing framework][lcut],
which is Copyright 2005–2010 Tony Bai, and released under the terms of
the Apache Licence, Version 2.0.


Norman Gray  
http://nxg.me.uk


[ITU-T recommendation]: http://www.itu.int/rec/T-REC-X.690-200811-I/en
[Wikipedia]: http://en.wikipedia.org/wiki/X.690
[RFC 4627]: http://www.ietf.org/rfc/rfc4627.txt
[RFC 7049]: http://www.ietf.org/rfc/rfc7049.txt
[BSD 2-clause licence]: http://opensource.org/licenses/BSD-2-Clause
[jasn]: https://code.google.com/p/jasn/
[lcut]: https://github.com/bigwhite/lcut