jws.h File Reference

Functions and data structures for interacting with JSON Web Signature (JWS) objects. More...

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#include "header.h"
#include "jwk.h"

Go to the source code of this file.

Typedefs
typedef struct _cjose_jws_int	cjose_jws_t

Functions
cjose_jws_t *	cjose_jws_sign (const cjose_jwk_t *jwk, cjose_header_t *protected_header, const uint8_t *plaintext, size_t plaintext_len, cjose_err *err)
bool	cjose_jws_export (cjose_jws_t *jws, const char **ser, cjose_err *err)
cjose_jws_t *	cjose_jws_import (const char *compact, size_t compact_len, cjose_err *err)
bool	cjose_jws_verify (cjose_jws_t *jws, const cjose_jwk_t *jwk, cjose_err *err)
bool	cjose_jws_get_plaintext (const cjose_jws_t *jws, uint8_t **plaintext, size_t *plaintext_len, cjose_err *err)
cjose_header_t *	cjose_jws_get_protected (cjose_jws_t *jws)
void	cjose_jws_release (cjose_jws_t *jws)

Detailed Description

Functions and data structures for interacting with JSON Web Signature (JWS) objects.

Typedef Documentation

cjose_jws_t

typedef struct _cjose_jws_int cjose_jws_t

An instance of a JWS object.

Function Documentation

cjose_jws_export()

bool cjose_jws_export	(	cjose_jws_t *	jws,
		const char **	ser,
		cjose_err *	err
	)

Creates a serialization of the given JWS object.

Note the current implementation only supports serialization to the JWS compact format.

Parameters

jws	[in] the JWS object to be serialized.
ser	[out] pointer to a compact serialization of this JWS. Note the returned string pointer is owned by the JWS, the caller should not attempt to free it directly, and note that it will be freed automatically when the JWS itself is released.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns

true if the serialization is successfully returned.

cjose_jws_get_plaintext()

bool cjose_jws_get_plaintext	(	const cjose_jws_t *	jws,
		uint8_t **	plaintext,
		size_t *	plaintext_len,
		cjose_err *	err
	)

Returns the plaintext data of the JWS payload.

Parameters

jws	[in] the JWS object for which the plaintext is requested.
plaintext	[out] pointer to the plaintext of this JWS. Note the returned buffer is owned by the JWS, the caller should not attempt to free it directly, and note that it will be freed automatically when the JWS itself is released.
plaintext_len	[out] number of bytes of plaintext in the returned plaintext buffer.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns

true if the plaintext is sucessfully returned.

cjose_jws_get_protected()

cjose_header_t* cjose_jws_get_protected

(

cjose_jws_t *

jws

)

Returns the protected header of the JWS payload.

NOTE: The returned header is still owned by the JWS object. Users must call cjose_header_retain() if it is expected to be valid after the owning cjose_jws_t is released.

Parameters

jws	[in] the JWS object for which the protected header is requested.

Returns

the (parsed) protected header

cjose_jws_import()

cjose_jws_t* cjose_jws_import	(	const char *	compact,
		size_t	compact_len,
		cjose_err *	err
	)

Creates a new JWS object from the given JWS compact serialization.

Note the current implementation only recognizes the JWS compact serialization format.

Parameters

compact	[in] a JWS in serialized form.
compact_len	[in] the length of the compact serialization.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns

a newly generated JWS object from the given JWS serialization.

cjose_jws_release()

void cjose_jws_release

(

cjose_jws_t *

jws

)

Releases the given JWS object.

Parameters

jws	the JWS to be released. If null, this is a no-op.

cjose_jws_sign()

cjose_jws_t* cjose_jws_sign	(	const cjose_jwk_t *	jwk,
		cjose_header_t *	protected_header,
		const uint8_t *	plaintext,
		size_t	plaintext_len,
		cjose_err *	err
	)

Creates a new JWS by signing the given plaintext within the given header and JWK.

Parameters

jwk	[in] the key to use for signing the JWS.
protected_header	[in] header values to include in the JWS header.
plaintext	[in] the plaintext to be signed as the JWS payload.
plaintext_len	[in] the length of the plaintext.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns

a newly generated JWS with the given plaintext as the payload.

cjose_jws_verify()

bool cjose_jws_verify	(	cjose_jws_t *	jws,
		const cjose_jwk_t *	jwk,
		cjose_err *	err
	)

Verifies the JWS object using the given JWK.

Parameters

jws	[in] the JWS object to verify.
jwk	[in] the key to use for verification.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns

true if verification was sucecssful.