decode.h File Reference

Core DECODE function for l8w8jwt. Use this to decode and validate a JWT! More...

#include "algs.h"
#include "claim.h"
#include "version.h"
#include "retcodes.h"
#include "timehelper.h"
#include <stddef.h>
#include <stdint.h>

Include dependency graph for decode.h:

Go to the source code of this file.

Classes
struct	l8w8jwt_decoding_params

Macros
#define	L8W8JWT_MAX_KEY_SIZE   8192

Enumerations
enum	l8w8jwt_validation_result {   L8W8JWT_VALID = (unsigned)0 , L8W8JWT_ISS_FAILURE = (unsigned)1 << (unsigned)0 , L8W8JWT_SUB_FAILURE = (unsigned)1 << (unsigned)1 , L8W8JWT_AUD_FAILURE = (unsigned)1 << (unsigned)2 ,   L8W8JWT_JTI_FAILURE = (unsigned)1 << (unsigned)3 , L8W8JWT_EXP_FAILURE = (unsigned)1 << (unsigned)4 , L8W8JWT_NBF_FAILURE = (unsigned)1 << (unsigned)5 , L8W8JWT_IAT_FAILURE = (unsigned)1 << (unsigned)6 ,   L8W8JWT_SIGNATURE_VERIFICATION_FAILURE = (unsigned)1 << (unsigned)7 , L8W8JWT_TYP_FAILURE = (unsigned)1 << (unsigned)8 }

Functions
L8W8JWT_API void	l8w8jwt_decoding_params_init (struct l8w8jwt_decoding_params *params)
L8W8JWT_API int	l8w8jwt_validate_decoding_params (struct l8w8jwt_decoding_params *params)
L8W8JWT_API int	l8w8jwt_decode (struct l8w8jwt_decoding_params *params, enum l8w8jwt_validation_result *out_validation_result, struct l8w8jwt_claim **out_claims, size_t *out_claims_length)
L8W8JWT_API int	l8w8jwt_decode_raw (struct l8w8jwt_decoding_params *params, enum l8w8jwt_validation_result *out_validation_result, char **out_header, size_t *out_header_length, char **out_payload, size_t *out_payload_length, uint8_t **out_signature, size_t *out_signature_length)
L8W8JWT_API int	l8w8jwt_decode_raw_no_validation (struct l8w8jwt_decoding_params *params, char **out_header, size_t *out_header_length, char **out_payload, size_t *out_payload_length, uint8_t **out_signature, size_t *out_signature_length)

Detailed Description

Core DECODE function for l8w8jwt. Use this to decode and validate a JWT!

Author

Raphael Beck

Enumeration Type Documentation

l8w8jwt_validation_result

enum l8w8jwt_validation_result

Enum containing the validation result flags.

Enumerator
L8W8JWT_VALID	The JWT is valid (according to the passed validation parameters).
L8W8JWT_ISS_FAILURE	The issuer claim is invalid.
L8W8JWT_SUB_FAILURE	The subject claim is invalid.
L8W8JWT_AUD_FAILURE	The audience claim is invalid.
L8W8JWT_JTI_FAILURE	The JWT ID claim is invalid.
L8W8JWT_EXP_FAILURE	The token is expired.
L8W8JWT_NBF_FAILURE	The token is not yet valid.
L8W8JWT_IAT_FAILURE	The token was not issued yet, are you from the future?
L8W8JWT_SIGNATURE_VERIFICATION_FAILURE	The token was potentially tampered with: its signature couldn't be verified.
L8W8JWT_TYP_FAILURE	The token's "typ" claim validation failed.

Function Documentation

l8w8jwt_decode()

L8W8JWT_API int l8w8jwt_decode	(	struct l8w8jwt_decoding_params *	params,
		enum l8w8jwt_validation_result *	out_validation_result,
		struct l8w8jwt_claim **	out_claims,
		size_t *	out_claims_length
	)

Decode (and validate) a JWT using specific parameters.

The resulting l8w8jwt_validation_result written into the passed "out_validation_result" pointer contains validation failure flags (see the l8w8jwt_validation_result enum docs for more details).

This only happens if decoding also succeeded: if the token is malformed, nothing will be written into "out_validation_result".

If validation succeeds, the l8w8jwt_validation_result receives the value 0 (enum value L8W8JWT_VALID).

The same applies to the "out_claims" argument: it is only allocated and written to if it (obviously) isn't NULL and if the decoding was also successful!

Parameters

params	The parameters to use for decoding and validating the token.
out_validation_result	Where to write the validation result flags into (0 means success). In case of a decoding failure this is set to -1 (or ~L8W8JWT_VALID)!
out_claims	[OPTIONAL] Where the decoded claims (header + payload claims together) should be written into. This pointer will be dereferenced + allocated, so make sure to pass a fresh pointer! If you don't need the claims, set this to NULL (they will only be validated, e.g. signature, exp, etc...). Check the note down below for more infos!
out_claims_length	Where to write the decoded claims count into. This will receive the value of how many claims were written into "out_claims" (0 if you decided to set "out_claims" to NULL).

Note

If you decide to keep the claims stored in the out_claims parameter, REMEMBER to call l8w8jwt_free_claims() on it once you're done using them!

Returns

Return code as defined in retcodes.h (this is NOT the validation result that's written into the out_validation_result argument; the returned int describes whether the actual parsing/decoding part failed).

l8w8jwt_decode_raw()

L8W8JWT_API int l8w8jwt_decode_raw	(	struct l8w8jwt_decoding_params *	params,
		enum l8w8jwt_validation_result *	out_validation_result,
		char **	out_header,
		size_t *	out_header_length,
		char **	out_payload,
		size_t *	out_payload_length,
		uint8_t **	out_signature,
		size_t *	out_signature_length
	)

Decode (and validate) a JWT using specific parameters, but instead of writing the collection of claims contained in the payload into an array of l8w8jwt_validation_result like in the standard l8w8jwt_decode function, the raw JWT payload's JSON string is written into the out_payload_json string, such that it can be parsed externally.

The resulting l8w8jwt_validation_result written into the passed "out_validation_result" pointer contains validation failure flags (see the l8w8jwt_validation_result enum docs for more details).

This only happens if decoding also succeeded: if the token is malformed, nothing will be written into "out_validation_result".

If validation succeeds, the l8w8jwt_validation_result receives the value 0 (enum value L8W8JWT_VALID).

The same applies to the "out_payload_json" argument: it is only allocated and written to if it (obviously) isn't NULL and if the decoding procedure was also successful!

Parameters

params	The parameters to use for decoding and validating the token.
out_validation_result	Where to write the validation result flags into (0 means success). In case of a decoding failure this is set to -1 (or ~L8W8JWT_VALID)!
out_header	Where to write the decoded JWT header JSON string into.
out_header_length	Where to write the length of out_header into.
out_payload	Where to write the decoded JWT's payload JSON string into, so that it can be parsed externally instead of by l8w8jwt directly.
out_payload_length	Where to write the length of out_payload into.
out_signature	Where to write the JWT's signature into.
out_signature_length	Where to write the length of out_signature into.

Returns

Return code as defined in retcodes.h (this is NOT the validation result that's written into the out_validation_result argument; the returned int describes whether the actual parsing/decoding part failed).

l8w8jwt_decode_raw_no_validation()

L8W8JWT_API int l8w8jwt_decode_raw_no_validation	(	struct l8w8jwt_decoding_params *	params,
		char **	out_header,
		size_t *	out_header_length,
		char **	out_payload,
		size_t *	out_payload_length,
		uint8_t **	out_signature,
		size_t *	out_signature_length
	)

Decodes a JWT without validating anything: neither claims nor signature. Just raw decoding, no validation!

Parameters

params	The parameters to use for decoding and validating the token.
out_header	Where to write the decoded JWT header JSON string into.
out_header_length	Where to write the length of out_header into.
out_payload	Where to write the decoded JWT's payload JSON string into, so that it can be parsed externally instead of by l8w8jwt directly.
out_payload_length	Where to write the length of out_payload into.
out_signature	Where to write the JWT's signature into.
out_signature_length	Where to write the length of out_signature into.

Returns

Return code as defined in retcodes.h

l8w8jwt_decoding_params_init()

L8W8JWT_API void l8w8jwt_decoding_params_init

(

struct l8w8jwt_decoding_params *

params

)

Initializes a l8w8jwt_decoding_params instance by setting its fields to default values.

Parameters

params

The l8w8jwt_decoding_params to initialize (set to default values).

l8w8jwt_validate_decoding_params()

L8W8JWT_API int l8w8jwt_validate_decoding_params

(

struct l8w8jwt_decoding_params *

params

)

Validates a set of l8w8jwt_decoding_params.

Parameters

params

The l8w8jwt_decoding_params to validate.

Returns

Return code as defined in retcodes.h