lws-lejp.h

Go to the documentation of this file.

/*
 * libwebsockets - small server side websockets and web server implementation
 *
 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 */

struct lejp_ctx;
struct lwsac;
 
#if !defined(LWS_ARRAY_SIZE)
#define LWS_ARRAY_SIZE(_x) (sizeof(_x) / sizeof(_x[0]))
#endif
#define LEJP_FLAG_WS_KEEP 64
#define LEJP_FLAG_WS_COMMENTLINE 32
 
enum lejp_states {
        LEJP_IDLE = 0,
        LEJP_MEMBERS = 1,
        LEJP_M_P = 2,
        LEJP_MP_STRING = LEJP_FLAG_WS_KEEP | 3,
        LEJP_MP_STRING_ESC = LEJP_FLAG_WS_KEEP | 4,
        LEJP_MP_STRING_ESC_U1 = LEJP_FLAG_WS_KEEP | 5,
        LEJP_MP_STRING_ESC_U2 = LEJP_FLAG_WS_KEEP | 6,
        LEJP_MP_STRING_ESC_U3 = LEJP_FLAG_WS_KEEP | 7,
        LEJP_MP_STRING_ESC_U4 = LEJP_FLAG_WS_KEEP | 8,
        LEJP_MP_DELIM = 9,
        LEJP_MP_VALUE = 10,
        LEJP_MP_VALUE_NUM_INT = LEJP_FLAG_WS_KEEP | 11,
        LEJP_MP_VALUE_NUM_EXP = LEJP_FLAG_WS_KEEP | 12,
        LEJP_MP_VALUE_TOK = LEJP_FLAG_WS_KEEP | 13,
        LEJP_MP_COMMA_OR_END = 14,
        LEJP_MP_ARRAY_END = 15,
};
 
enum lejp_reasons {
        LEJP_CONTINUE = -1,
        LEJP_REJECT_IDLE_NO_BRACE = -2,
        LEJP_REJECT_MEMBERS_NO_CLOSE = -3,
        LEJP_REJECT_MP_NO_OPEN_QUOTE = -4,
        LEJP_REJECT_MP_STRING_UNDERRUN = -5,
        LEJP_REJECT_MP_ILLEGAL_CTRL = -6,
        LEJP_REJECT_MP_STRING_ESC_ILLEGAL_ESC = -7,
        LEJP_REJECT_ILLEGAL_HEX = -8,
        LEJP_REJECT_MP_DELIM_MISSING_COLON = -9,
        LEJP_REJECT_MP_DELIM_BAD_VALUE_START = -10,
        LEJP_REJECT_MP_VAL_NUM_INT_NO_FRAC = -11,
        LEJP_REJECT_MP_VAL_NUM_FORMAT = -12,
        LEJP_REJECT_MP_VAL_NUM_EXP_BAD_EXP = -13,
        LEJP_REJECT_MP_VAL_TOK_UNKNOWN = -14,
        LEJP_REJECT_MP_C_OR_E_UNDERF = -15,
        LEJP_REJECT_MP_C_OR_E_NOTARRAY = -16,
        LEJP_REJECT_MP_ARRAY_END_MISSING = -17,
        LEJP_REJECT_STACK_OVERFLOW = -18,
        LEJP_REJECT_MP_DELIM_ISTACK = -19,
        LEJP_REJECT_NUM_TOO_LONG = -20,
        LEJP_REJECT_MP_C_OR_E_NEITHER = -21,
        LEJP_REJECT_UNKNOWN = -22,
        LEJP_REJECT_CALLBACK = -23,
        LEJP_REJECT_MP_KEY_ILLEGAL_CHAR = -24,
        LEJP_REJECT_PATH_TOO_LONG = -25
};
 
#define LEJP_FLAG_CB_IS_VALUE 64
 
enum lejp_callbacks {
        LEJPCB_CONSTRUCTED      = 0,
        LEJPCB_DESTRUCTED       = 1,
 
        LEJPCB_START            = 2,
        LEJPCB_COMPLETE         = 3,
        LEJPCB_FAILED           = 4,
 
        LEJPCB_PAIR_NAME        = 5,
 
        LEJPCB_VAL_TRUE         = LEJP_FLAG_CB_IS_VALUE | 6,
        LEJPCB_VAL_FALSE        = LEJP_FLAG_CB_IS_VALUE | 7,
        LEJPCB_VAL_NULL         = LEJP_FLAG_CB_IS_VALUE | 8,
        LEJPCB_VAL_NUM_INT      = LEJP_FLAG_CB_IS_VALUE | 9,
        LEJPCB_VAL_NUM_FLOAT    = LEJP_FLAG_CB_IS_VALUE | 10,
        LEJPCB_VAL_STR_START    = 11, /* notice handle separately */
        LEJPCB_VAL_STR_CHUNK    = LEJP_FLAG_CB_IS_VALUE | 12,
        LEJPCB_VAL_STR_END      = LEJP_FLAG_CB_IS_VALUE | 13,
 
        LEJPCB_ARRAY_START      = 14,
        LEJPCB_ARRAY_END        = 15,
 
        LEJPCB_OBJECT_START     = 16,
        LEJPCB_OBJECT_END       = 17,
 
        LEJPCB_USER_START       = 32,
};

LWS_EXTERN signed char _lejp_callback(struct lejp_ctx *ctx, char reason);
 
typedef signed char (*lejp_callback)(struct lejp_ctx *ctx, char reason);
 
#ifndef LEJP_MAX_PARSING_STACK_DEPTH
#define LEJP_MAX_PARSING_STACK_DEPTH 10
#endif
#ifndef LEJP_MAX_DEPTH
#if defined(LWS_ESP_PLATFORM)
#define LEJP_MAX_DEPTH 16
#else
#define LEJP_MAX_DEPTH 64
#endif
#endif
#ifndef LEJP_MAX_INDEX_DEPTH
#if defined(LWS_ESP_PLATFORM)
#define LEJP_MAX_INDEX_DEPTH 12
#else
#define LEJP_MAX_INDEX_DEPTH 64
#endif
#endif
#ifndef LEJP_MAX_PATH
#define LEJP_MAX_PATH 192
#endif
#ifndef LEJP_STRING_CHUNK
/* must be >= 30 to assemble floats */
#define LEJP_STRING_CHUNK 254
#endif
 
/*
 * These are tunable, but every index into the arrays they size is a uint8_t
 * in struct lejp_ctx, so they are hard-capped: LEJP_MAX_PATH, LEJP_MAX_DEPTH,
 * LEJP_MAX_INDEX_DEPTH and LEJP_MAX_PARSING_STACK_DEPTH must each be <= 255,
 * and LEJP_STRING_CHUNK <= 254.  Raising one past its cap does not overflow
 * the array, but the bounds checks stop firing and the parser silently
 * corrupts what it collected.
 */
 
#if LEJP_MAX_PATH > 255 || LEJP_MAX_DEPTH > 255 || \
    LEJP_MAX_INDEX_DEPTH > 255 || LEJP_MAX_PARSING_STACK_DEPTH > 255 || \
    LEJP_STRING_CHUNK > 254
#error "LEJP_ size knob is larger than its uint8_t index can represent"
#endif
 
enum num_flags {
        LEJP_SEEN_MINUS         = (1 << 0),
        LEJP_SEEN_POINT         = (1 << 1),
        LEJP_SEEN_POST_POINT    = (1 << 2),
        LEJP_SEEN_EXP           = (1 << 3)
};
 
struct _lejp_stack {
        char                    s; /* lejp_state stack*/
        uint8_t                 p;      /* path length, 0 .. LEJP_MAX_PATH - 1 */
        char                    i; /* index array length */
        char                    b; /* user bitfield */
};
 
struct _lejp_parsing_stack {
        void                    *user;  /* private to the stack level */
        signed char             (*callback)(struct lejp_ctx *ctx, char reason);
        const char * const      *paths;
        uint8_t                 count_paths;
        uint8_t                 ppos;
        uint8_t                 path_match;
};
 
typedef struct lejp_string_piece {
        struct lejp_string_piece        *next;
        const char                      *piece;
        size_t                          len;
} lejp_string_piece_t;
 
typedef struct {
        lejp_string_piece_t     *sph;
        lejp_string_piece_t     **sp_next;
        int                     pieces;
        size_t                  asl;
        char                    *fp;
} lejp_string_unifier_t;
 
struct lejp_ctx {
 
        /* sorted by type for most compact alignment
         *
         * pointers
         */
        void *user;
 
        /* arrays */
 
        struct _lejp_parsing_stack pst[LEJP_MAX_PARSING_STACK_DEPTH];
        struct _lejp_stack st[LEJP_MAX_DEPTH];
        uint16_t i[LEJP_MAX_INDEX_DEPTH]; /* index array */
        uint16_t wild[LEJP_MAX_INDEX_DEPTH]; /* index array */
        char path[LEJP_MAX_PATH];
        char buf[LEJP_STRING_CHUNK + 1];
 
        lejp_string_unifier_t   su;
 
        /* size_t */
 
        size_t path_stride; /* 0 means default ptr size, else stride */
 
        /* int */
 
        uint32_t line;
 
        /* short */
 
        uint16_t uni;
        uint16_t uni_hi; /* pending \uD800-\uDBFF surrogate half, or 0 */
#define LEJP_FLAG_FEAT_OBJECT_INDEXES                           (1 << 0)
#define LEJP_FLAG_FEAT_LEADING_WC                               (1 << 1)
/*
 * Reject object key names containing the characters lejp uses to represent
 * the document structure in ctx->path, ie, '.', '[' and ']'.  Without this,
 * a peer can choose a key name that synthesizes the same path as a completely
 * different document shape, eg, {"s[].foo":1} produces the same path as
 * {"s":[{"foo":1}]}.  It's optional since a key legitimately containing '.'
 * (eg, a hostname) is not that unusual; set it if your paths care.
 */
#define LEJP_FLAG_FEAT_STRICT_KEY_CHARS                         (1 << 2)
/*
 * Accept lejp's nonstandard '#' to-end-of-line comment extension, outside of
 * strings, at any depth.  RFC 8259 has no comments, so with this set lejp
 * assigns a meaning to documents every conformant JSON parser rejects, eg,
 * {"a":1#,"b":2 LF } is {"a":1} to lejp and a syntax error to everybody else.
 * Wherever the same bytes are also seen by another parser - a JOSE header the
 * relying party also reads, a policy a management tool also reads - the two
 * disagree about what the document says, and lejp's view is the one the
 * security decision is made on.  So it's off by default and network-facing
 * parses must leave it off; it exists for hand-written, locally-owned config
 * files, and in-tree only lejp-conf.c (the lwsws config parser) sets it.
 *
 * Deliberately not part of LEJP_FLAG_LATEST, which means "the best current
 * behaviours", ie, the strictest.
 */
#define LEJP_FLAG_FEAT_COMMENTS                                 (1 << 3)
#define LEJP_FLAG_LATEST \
                                        (LEJP_FLAG_FEAT_OBJECT_INDEXES | \
                                         LEJP_FLAG_FEAT_LEADING_WC | \
                                         LEJP_FLAG_FEAT_STRICT_KEY_CHARS)
        uint16_t flags;
 
        /* char */
 
        uint8_t npos;
        uint8_t dcount;
        uint8_t f;
        uint8_t sp; /* stack head */
        uint8_t ipos; /* index stack depth */
        uint8_t count_paths;
        uint8_t path_match;
        uint8_t path_match_len;
        uint8_t wildcount;
        uint8_t pst_sp; /* parsing stack head */
        uint8_t outer_array;
};
 
LWS_VISIBLE LWS_EXTERN void
lejp_construct(struct lejp_ctx *ctx,
               signed char (*callback)(struct lejp_ctx *ctx, char reason),
               void *user, const char * const *paths, unsigned char paths_count);
 
LWS_VISIBLE LWS_EXTERN void
lejp_destruct(struct lejp_ctx *ctx);
 
LWS_VISIBLE LWS_EXTERN int
lejp_parse(struct lejp_ctx *ctx, const unsigned char *json, int len);
 
LWS_VISIBLE LWS_EXTERN void
lejp_change_callback(struct lejp_ctx *ctx,
                     signed char (*callback)(struct lejp_ctx *ctx, char reason));
 
/*
 * push the current paths / paths_count and lejp_cb to a stack in the ctx, and
 * start using the new ones
 */
LWS_VISIBLE LWS_EXTERN int
lejp_parser_push(struct lejp_ctx *ctx, void *user, const char * const *paths,
                 unsigned char paths_count, lejp_callback lejp_cb);
 
/*
 * pop the previously used paths / paths_count and lejp_cb, and continue
 * parsing using those as before
 */
LWS_VISIBLE LWS_EXTERN int
lejp_parser_pop(struct lejp_ctx *ctx);
 
/* exported for use when reevaluating a path for use with a subcontext */
LWS_VISIBLE LWS_EXTERN void
lejp_check_path_match(struct lejp_ctx *ctx);
 
LWS_VISIBLE LWS_EXTERN int
lejp_get_wildcard(struct lejp_ctx *ctx, int wildcard, char *dest, int len);
 
LWS_VISIBLE LWS_EXTERN const char *
lejp_error_to_string(int e);
 
LWS_VISIBLE LWS_EXTERN int
lejp_string_unify(struct lejp_ctx *ctx, struct lwsac **ac);
 
LWS_VISIBLE LWS_EXTERN int
lejp_string_unify_part(struct lejp_ctx *ctx, struct lwsac **ac, char reason);