Overview

HTTPS SSH

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 decoder 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 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, 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