JSON Web Signature

Functions
LWS_VISIBLE LWS_EXTERN int	lws_jws_confirm_sig (const char *in, size_t len, struct lws_jwk *jwk)
LWS_VISIBLE LWS_EXTERN int	lws_jws_sign_from_b64 (const char *b64_hdr, size_t hdr_len, const char *b64_pay, size_t pay_len, char *b64_sig, size_t sig_len, enum lws_genhash_types hash_type, struct lws_jwk *jwk)
LWS_VISIBLE LWS_EXTERN int	lws_jws_create_packet (struct lws_jwk *jwk, const char *payload, size_t len, const char *nonce, char *out, size_t out_len)
LWS_VISIBLE LWS_EXTERN int	lws_jws_base64_enc (const char *in, size_t in_len, char *out, size_t out_max)

Detailed Description

JSON Web Signature API

Lws provides an API to check and create RFC7515 JSON Web Signatures

SHA256/384/512 HMAC, and RSA 256/384/512 are supported.

The API uses your TLS library crypto, but works exactly the same no matter what you TLS backend is.

Function Documentation

lws_jws_base64_enc()

LWS_VISIBLE LWS_EXTERN int lws_jws_base64_enc	(	const char *	in,
		size_t	in_len,
		char *	out,
		size_t	out_max
	)

#include <lib/libwebsockets.h>

lws_jws_base64_enc() - encode input data into b64url data

Parameters

in	the incoming plaintext
in_len	the length of the incoming plaintext in bytes
out	the buffer to store the b64url encoded data to
out_max	the length of out in bytes

Returns either -1 if problems, or the number of bytes written to out.

lws_jws_create_packet()

LWS_VISIBLE LWS_EXTERN int lws_jws_create_packet	(	struct lws_jwk *	jwk,
		const char *	payload,
		size_t	len,
		const char *	nonce,
		char *	out,
		size_t	out_len
	)

#include <lib/libwebsockets.h>

lws_jws_create_packet() - add b64 sig to b64 hdr + payload

Parameters

jwk	the struct lws_jwk containing the signing key
payload	unencoded payload JSON
len	length of unencoded payload JSON
nonce	Nonse string to include in protected header
out	buffer to take signed packet
out_len	size of out buffer

This creates a "flattened" JWS packet from the jwk and the plaintext payload, and signs it. The packet is written into out.

This does the whole packet assembly and signing, calling through to lws_jws_sign_from_b64() as part of the process.

Returns the length written to out, or -1.

lws_jws_sign_from_b64()

LWS_VISIBLE LWS_EXTERN int lws_jws_sign_from_b64	(	const char *	b64_hdr,
		size_t	hdr_len,
		const char *	b64_pay,
		size_t	pay_len,
		char *	b64_sig,
		size_t	sig_len,
		enum lws_genhash_types	hash_type,
		struct lws_jwk *	jwk
	)

#include <lib/libwebsockets.h>

lws_jws_sign_from_b64() - add b64 sig to b64 hdr + payload

Parameters

b64_hdr	protected header encoded in b64, may be NULL
hdr_len	bytes in b64 coding of protected header
b64_pay	payload encoded in b64
pay_len	bytes in b64 coding of payload
b64_sig	buffer to write the b64 encoded signature into
sig_len	max bytes we can write at b64_sig
hash_type	one of LWS_GENHASH_TYPE_SHA[256|384|512]
jwk	the struct lws_jwk containing the signing key

This adds a b64-coded JWS signature of the b64-encoded protected header and b64-encoded payload, at b64_sig. The signature will be as large as the N element of the RSA key when the RSA key is used, eg, 512 bytes for a 4096-bit key, and then b64-encoding on top.

In some special cases, there is only payload to sign and no header, in that case b64_hdr may be NULL, and only the payload will be hashed before signing.

Returns the length of the encoded signature written to b64_sig, or -1.