include/libwebsockets/lws-lecp.h

/*
 * libwebsockets - small server side websockets and web server implementation
 *
 * Copyright (C) 2010 - 2021 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.
 */

/** \defgroup lecp CBOR parser
 * ##CBOR parsing related functions
 * \ingroup lwsapi
 *
 * LECP is an extremely lightweight CBOR stream parser included in lws.  It
 * is aligned in approach with the LEJP JSON stream parser, with some additional
 * things needed for CBOR.
 */
//@{

#ifndef LECP_MAX_PARSING_STACK_DEPTH
#define LECP_MAX_PARSING_STACK_DEPTH	5
#endif
#ifndef LECP_MAX_DEPTH
#define LECP_MAX_DEPTH			12
#endif
#ifndef LECP_MAX_INDEX_DEPTH
#define LECP_MAX_INDEX_DEPTH		8
#endif
#ifndef LECP_MAX_PATH
#define LECP_MAX_PATH			128
#endif
#ifndef LECP_STRING_CHUNK
/* must be >= 30 to assemble floats */
#define LECP_STRING_CHUNK		254
#endif

#define LECP_FLAG_CB_IS_VALUE 64

/*
 * CBOR initial byte 3 x MSB bits are these
 */

enum {
	LWS_CBOR_MAJTYP_UINT		= 0 << 5,
	LWS_CBOR_MAJTYP_INT_NEG		= 1 << 5,
	LWS_CBOR_MAJTYP_BSTR		= 2 << 5,
	LWS_CBOR_MAJTYP_TSTR		= 3 << 5,
	LWS_CBOR_MAJTYP_ARRAY		= 4 << 5,
	LWS_CBOR_MAJTYP_MAP		= 5 << 5,
	LWS_CBOR_MAJTYP_TAG		= 6 << 5,
	LWS_CBOR_MAJTYP_FLOAT		= 7 << 5,  /* also BREAK */

	LWS_CBOR_MAJTYP_MASK		= 7 << 5,

	/*
	 * For the low 5 bits of the opcode, 0-23 are literals, unless it's
	 * FLOAT.
	 *
	 * 24 = 1 byte; 25 = 2..., 26 = 4... and 27 = 8 bytes following literal.
	 */
	LWS_CBOR_1			= 24,
	LWS_CBOR_2			= 25,
	LWS_CBOR_4			= 26,
	LWS_CBOR_8			= 27,

	LWS_CBOR_RESERVED		= 28,

	LWS_CBOR_SUBMASK		= 0x1f,

	/*
	 * Major type 7 discriminators in low 5 bits
	 * 0 - 23 is SIMPLE implicit value (like, eg, LWS_CBOR_SWK_TRUE)
	 */
	LWS_CBOR_SWK_FALSE		= 20,
	LWS_CBOR_SWK_TRUE		= 21,
	LWS_CBOR_SWK_NULL		= 22,
	LWS_CBOR_SWK_UNDEFINED		= 23,

	LWS_CBOR_M7_SUBTYP_SIMPLE_X8	= 24, /* simple with additional byte */
	LWS_CBOR_M7_SUBTYP_FLOAT16	= 25,
	LWS_CBOR_M7_SUBTYP_FLOAT32	= 26,
	LWS_CBOR_M7_SUBTYP_FLOAT64	= 27,
	LWS_CBOR_M7_BREAK		= 31,

/* 28, 29, 30 are illegal.
 *
 * 31 is illegal for UINT, INT_NEG, and TAG;
 *               for BSTR, TSTR, ARRAY and MAP it means "indefinite length", ie,
 *               it's made up of an endless amount of determinite-length
 *               fragments terminated with a BREAK (FLOAT | 31) instead of the
 *               next determinite-length fragment.  The second framing level
 *               means no need for escapes for BREAK in the data.
 */

	LWS_CBOR_INDETERMINITE		= 31,

/*
 * Well-known tags
 */

	LWS_CBOR_WKTAG_DATETIME_STD	= 0, /* text */
	LWS_CBOR_WKTAG_DATETIME_EPOCH	= 1, /* int or float */
	LWS_CBOR_WKTAG_BIGNUM_UNSIGNED	= 2, /* byte string */
	LWS_CBOR_WKTAG_BIGNUM_NEGATIVE	= 3, /* byte string */
	LWS_CBOR_WKTAG_DECIMAL_FRAC	= 4, /* array */
	LWS_CBOR_WKTAG_BIGFLOAT		= 5, /* array */

	LWS_CBOR_WKTAG_COSE_ENC0	= 16,
	LWS_CBOR_WKTAG_COSE_MAC0	= 17,
	LWS_CBOR_WKTAG_COSE_SIGN1	= 18,

	LWS_CBOR_WKTAG_TO_B64U		= 21, /* any */
	LWS_CBOR_WKTAG_TO_B64		= 22, /* any */
	LWS_CBOR_WKTAG_TO_B16		= 23, /* any */
	LWS_CBOR_WKTAG_CBOR		= 24, /* byte string */

	LWS_CBOR_WKTAG_URI		= 32, /* text string */
	LWS_CBOR_WKTAG_B64U		= 33, /* text string */
	LWS_CBOR_WKTAG_B64		= 34, /* text string */
	LWS_CBOR_WKTAG_MIME		= 36, /* text string */

	LWS_CBOR_WKTAG_COSE_ENC		= 96,
	LWS_CBOR_WKTAG_COSE_MAC		= 97,
	LWS_CBOR_WKTAG_COSE_SIGN	= 98,

	LWS_CBOR_WKTAG_SELFDESCCBOR	= 55799
};

enum lecp_callbacks {
	LECPCB_CONSTRUCTED		= 0,
	LECPCB_DESTRUCTED		= 1,

	LECPCB_COMPLETE			= 3,
	LECPCB_FAILED			= 4,

	LECPCB_PAIR_NAME		= 5,

	LECPCB_VAL_TRUE			= LECP_FLAG_CB_IS_VALUE | 6,
	LECPCB_VAL_FALSE		= LECP_FLAG_CB_IS_VALUE | 7,
	LECPCB_VAL_NULL			= LECP_FLAG_CB_IS_VALUE | 8,
	LECPCB_VAL_NUM_INT		= LECP_FLAG_CB_IS_VALUE | 9,
	LECPCB_VAL_RESERVED		= LECP_FLAG_CB_IS_VALUE | 10,
	LECPCB_VAL_STR_START		= 11, /* notice handle separately */
	LECPCB_VAL_STR_CHUNK		= LECP_FLAG_CB_IS_VALUE | 12,
	LECPCB_VAL_STR_END		= LECP_FLAG_CB_IS_VALUE | 13,

	LECPCB_ARRAY_START		= 14,
	LECPCB_ARRAY_END		= 15,

	LECPCB_OBJECT_START		= 16,
	LECPCB_OBJECT_END		= 17,

	LECPCB_TAG_START		= 18,
	LECPCB_TAG_END			= 19,

	LECPCB_VAL_NUM_UINT		= LECP_FLAG_CB_IS_VALUE | 20,
	LECPCB_VAL_UNDEFINED		= LECP_FLAG_CB_IS_VALUE | 21,
	LECPCB_VAL_FLOAT16		= LECP_FLAG_CB_IS_VALUE | 22,
	LECPCB_VAL_FLOAT32		= LECP_FLAG_CB_IS_VALUE | 23,
	LECPCB_VAL_FLOAT64		= LECP_FLAG_CB_IS_VALUE | 24,

	LECPCB_VAL_SIMPLE		= LECP_FLAG_CB_IS_VALUE | 25,

	LECPCB_VAL_BLOB_START		= 26, /* notice handle separately */
	LECPCB_VAL_BLOB_CHUNK		= LECP_FLAG_CB_IS_VALUE | 27,
	LECPCB_VAL_BLOB_END		= LECP_FLAG_CB_IS_VALUE | 28,

	LECPCB_ARRAY_ITEM_START		= 29,
	LECPCB_ARRAY_ITEM_END		= 30,

	LECPCB_LITERAL_CBOR		= 31,
};

enum lecp_reasons {
	LECP_CONTINUE			= -1,
	LECP_REJECT_BAD_CODING		= -2,
	LECP_REJECT_UNKNOWN		= -3,
	LECP_REJECT_CALLBACK		= -4,
	LECP_STACK_OVERFLOW		= -5,
};


struct lecp_item {
	union {
		uint64_t	u64;
		int64_t		i64;

		uint64_t	u32;

		uint16_t	hf;
#if defined(LWS_WITH_CBOR_FLOAT)
		float		f;
		double		d;
#else
		uint32_t	f;
		uint64_t	d;
#endif
	} u;
	uint8_t			opcode;
};

struct lecp_ctx;
typedef signed char (*lecp_callback)(struct lecp_ctx *ctx, char reason);

struct _lecp_stack {
	char			s; /* lejp_state stack*/
	uint8_t			p; /* path length */
	char			i; /* index array length */
	char			indet; /* indeterminite */
	char			intermediate; /* in middle of string */

	char			pop_iss;
	uint64_t		tag;
	uint64_t		collect_rem;
	uint32_t		ordinal;
	uint8_t			opcode;
	uint8_t			send_new_array_item;
	uint8_t			barrier;
};

struct _lecp_parsing_stack {
	void			*user;	/* private to the stack level */
	lecp_callback		cb;
	const char * const	*paths;
	uint8_t			count_paths;
	uint8_t			ppos;
	uint8_t			path_match;
};

struct lecp_ctx {

	/* sorted by type for most compact alignment
	 *
	 * pointers
	 */
	void *user;
	uint8_t			*collect_tgt;

	/* arrays */

	struct _lecp_parsing_stack pst[LECP_MAX_PARSING_STACK_DEPTH];
	struct _lecp_stack	st[LECP_MAX_DEPTH];
	uint16_t		i[LECP_MAX_INDEX_DEPTH]; /* index array */
	uint16_t		wild[LECP_MAX_INDEX_DEPTH]; /* index array */
	char			path[LECP_MAX_PATH];
	uint8_t			cbor[64]; /* literal cbor capture */

	struct lecp_item	item;


	/* size_t */

	size_t			path_stride; /* 0 means default ptr size, else
					      * stride...  allows paths to be
					      * provided composed inside a
					      * larger user struct instead of a
					      * duplicated array */
	size_t			used_in;     /* bytes of input consumed */

	/* short */

	uint16_t 		uni;

	/* 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;
	uint8_t			cbor_pos;
	uint8_t			literal_cbor_report;
	char			present; /* temp for cb reason to use */

	uint8_t			be; /* big endian */

	/* at end so we can memset the rest of it */

	char buf[LECP_STRING_CHUNK + 1];
};

struct lws_lec_pctx;
typedef struct lws_lec_pctx lws_lec_pctx_t;

enum lws_lec_pctx_ret {
	LWS_LECPCTX_RET_FINISHED		= 0,
	LWS_LECPCTX_RET_AGAIN, /* call again to continue writing buffer */
	LWS_LECPCTX_RET_FAIL /* something broken, eg, format string */
};

enum cbp_state {
	CBPS_IDLE,
	CBPS_PC1,
	CBPS_PC2,
	CBPS_PC3,

	CBPS_STRING_BODY,

	CBPS_NUM_LIT,

	CBPS_STRING_LIT,

	CBPS_CONTYPE,
};

typedef struct lws_lec_pctx {
	uint8_t			stack[16];
	uint8_t			vaa[16];
	uint8_t			indet[16];
	uint8_t			scratch[24];
	uint8_t			*start;	   /* the beginning of the out buf */
	uint8_t			*buf;	   /* cur pos in output buf */
	uint8_t			*end;	   /* the end of the output buf */

	const uint8_t		*ongoing_src;
	uint64_t		ongoing_len;
	uint64_t		ongoing_done;

	struct lecp_item	item;

	size_t			used;	   /* number of bytes valid from start */

	int			opaque[4]; /* ignored by lws, caller may use */

	enum cbp_state		state;
	unsigned int		fmt_pos;
	uint8_t			sp;
	uint8_t			scratch_len;
	uint8_t			escflag;
	uint8_t			_long;
	uint8_t			vaa_pos;
	uint8_t			dotstar;
} lws_lec_pctx_t;

LWS_VISIBLE LWS_EXTERN void
lws_lec_int(lws_lec_pctx_t *ctx, uint8_t opcode, uint8_t indet, uint64_t num);

LWS_VISIBLE LWS_EXTERN int
lws_lec_scratch(lws_lec_pctx_t *ctx);

/*
 * lws_lec_init() - prepare a cbor writing context
 *
 * \param ctx: the cbor writing context to prepare
 * \param buf: the output buffer start
 * \param len: the amount of the output buffer we can use
 *
 * Prepares a cbor writing context so that les_lec_printf can be used to
 * write into it.
 */
LWS_VISIBLE LWS_EXTERN void
lws_lec_init(lws_lec_pctx_t *ctx, uint8_t *buf, size_t len);

/*
 * lws_lec_setbuf() - update the output buffer for an initialized cbor writing ctx
 *
 * \param ctx: the cbor writing context to prepare
 * \param buf: the output buffer start
 * \param len: the amount of the output buffer we can use
 *
 * Leaves the cbor writing context state as it is, but resets the output buffer
 * it writes into as given in \p buf and \p len
 */
LWS_VISIBLE LWS_EXTERN void
lws_lec_setbuf(lws_lec_pctx_t *ctx, uint8_t *buf, size_t len);

/*
 * lws_lec_vsprintf() - write into a cbor writing context
 *
 * \param ctx: the cbor writing context to prepare
 * \param format: a printf style argument map
 * \param args: the va args
 *
 * CBOR-aware vsprintf which pauses output when it fills the output buffer.  You
 * can call it again with the same args and same lws_lex_pctx to resume filling
 *
 * Returns either LWS_LECPCTX_RET_FINISHED if we have nothing left over that we
 * want to put in the buffer, or LWS_LECPCTX_RET_AGAIN if the function should
 * be called again with the same arguments (perhaps into a different output
 * buffer) to continue emitting output from where it left off.
 *
 * If LWS_LECPCTX_RET_AGAIN is returned, lws_lec_setbuf() must be used on the
 * context to reset or change the output buffer before calling again.
 *
 * The number of bytes placed in the output buffer is available in ctx->used.
 *
 * \p format is a printf-type format string that is specialized for CBOR
 * generation.  It understands the following specifiers
 *
 * |`123`||unsigned literal number|
 * |`-123`||signed literal number|
 * |`%u`|`unsigned int`|number|
 * |`%lu`|`unsigned long int`|number|
 * |`%llu`|`unsigned long long int`|number|
 * |`%d`|`signed int`|number|
 * |`%ld`|`signed long int`|number|
 * |`%lld`|`signed long long int`|number|
 * |`%f`|`double`|floating point number|
 * |`123(...)`||literal tag and scope|
 * |`%t(...)`|`unsigned int`|tag and scope|
 * |`%lt(...)`|`unsigned long int`|tag and scope|
 * |`%llt(...)`|`unsigned long long int`|tag and scope|
 * |`[...]`||Array (fixed len if `]` in same format string)|
 * |`{...}`||Map (fixed len if `}` in same format string)|
 * |`<t...>`||Container for indeterminite text string frags|
 * |`<b...>`||Container for indeterminite binary string frags|
 * |`'string'`||Literal text of known length|
 * |`%s`|`const char *`|NUL-terminated string|
 * |`%.*s`|`int`, `const char *`|length-specified string|
 * |`%.*b`|`int`, `const uint8_t *`|length-specified binary|
 * |`:`||separator between Map items (a:b)|
 * |`,`||separator between Map pairs or array items|
 *
 * See READMEs/README.cbor-lecp.md for more details.
 */
LWS_VISIBLE LWS_EXTERN enum lws_lec_pctx_ret
lws_lec_vsprintf(lws_lec_pctx_t *ctx, const char *format, va_list args);

/*
 * lws_lec_printf() - write into a cbor writing context
 *
 * \param ctx: the cbor writing context to prepare
 * \param format: a printf style argument map
 * \param ...: format args
 *
 * See lws_lec_vsprintf() for format details.  This is the most common way
 * to format the CBOR output.
 *
 * See READMEs/README.cbor-lecp.md for more details.
 */
LWS_VISIBLE LWS_EXTERN enum lws_lec_pctx_ret
lws_lec_printf(lws_lec_pctx_t *ctx, const char *format, ...);

/**
 * lecp_construct() - Construct an LECP parser context
 *
 * \param ctx: the parser context object to be initialized
 * \param cb: the user callback to receive the parsing events
 * \param user: an opaque user pointer available at \p cb
 * \param paths: an optional array of parsing paths
 * \param paths_count: how many paths in \p paths
 *
 * Prepares an LECP parser context for parsing.
 */
LWS_VISIBLE LWS_EXTERN void
lecp_construct(struct lecp_ctx *ctx, lecp_callback cb, void *user,
	       const char * const *paths, unsigned char paths_count);

/**
 * lecp_destruct() - Destroys an LECP parser context
 *
 * \param ctx: the parser context object to be destroyed
 */
LWS_VISIBLE LWS_EXTERN void
lecp_destruct(struct lecp_ctx *ctx);

/**
 * lecp_parse() - parses a chunk of input CBOR
 *
 * \p ctx: the parsing context
 * \p cbor: the start of the chunk of CBOR
 * \p len: the number of bytes of CBOR available at \p cbor
 *
 * Returns LECP_CONTINUE if more input needed, one of enum lecp_reasons for a
 * fatal error, else 0 for successful parsing completion.
 *
 * On success or _CONTINUE, ctx->used_in is set to the number of input bytes
 * consumed.
 */
LWS_VISIBLE LWS_EXTERN int
lecp_parse(struct lecp_ctx *ctx, const uint8_t *cbor, size_t len);

LWS_VISIBLE LWS_EXTERN void
lecp_change_callback(struct lecp_ctx *ctx, lecp_callback cb);

LWS_VISIBLE LWS_EXTERN const char *
lecp_error_to_string(int e);

/**
 * lecp_parse_report_raw() - turn cbor raw reporting on and off
 *
 * \param ctx: the lecp context
 * \param on: 0 to disable (defaults disabled), 1 to enable
 *
 * For cose_sign, it needs access to raw cbor subtrees for the hash input.
 * This api causes LECPCB_LITERAL_CBOR parse callbacks when there are
 * ctx->cbor_pos bytes of raw cbor available in ctx->cbor[]. the callbacks
 * occur when the ctx->cbor[] buffer fills or if it holds anything when this
 * spi is used to stop the reports.
 *
 * The same CBOR that is being captured continues to be passed for parsing.
 */
LWS_VISIBLE LWS_EXTERN void
lecp_parse_report_raw(struct lecp_ctx *ctx, int on);

/**
 * lecp_parse_map_is_key() - return nonzero if we're in a map and this is a key
 *
 * \param ctx: the lwcp context
 *
 * Checks if the current value is a key in a map, ie, that you are on a "key" in
 * a list of "{key: value}" pairs.  Zero means you're either not in a map or not
 * on the key part, and nonzero means you are in a map and on a key part.
 */
LWS_VISIBLE LWS_EXTERN int
lecp_parse_map_is_key(struct lecp_ctx *ctx);

LWS_VISIBLE LWS_EXTERN int
lecp_parse_subtree(struct lecp_ctx *ctx, const uint8_t *in, size_t len);

/*
 * Helpers for half-float
 */

LWS_VISIBLE LWS_EXTERN void
lws_singles2halfp(uint16_t *hp, uint32_t x);

LWS_VISIBLE LWS_EXTERN void
lws_halfp2singles(uint32_t *xp, uint16_t h);

//@}