Functions used to create and destroy JWT objects. More...

Functions
int	jwt_new (jwt_t **jwt)
	Allocate a new, empty, JWT object.

int	jwt_decode (jwt_t *jwt, const char token, const unsigned char *key, int key_len)
	Decode an existing JWT and allocate a new JWT object from it.

int	jwt_decode_2 (jwt_t *jwt, const char token, jwt_key_p_t key_provider)
	Like jwt_decode(), but the key will be obtained via the key provider.

void	jwt_free (jwt_t *jwt)
	Free a JWT object and any other resources it is using.

jwt_t *	jwt_dup (jwt_t *jwt)
	Duplicate an existing JWT object.

Detailed Description

Functions used to create and destroy JWT objects.

Generally, one would use the jwt_new() function to create an object from scratch and jwt_decode() to create and verify and object from an existing token.

Note, when using RSA keys (e.g. with RS256), the key is expected to be a private key in PEM format. If the RSA private key requires a passphrase, the default is to request it on the command line from stdin. However, you can override this using OpenSSL's default_passwd routines. For example, using SSL_CTX_set_default_passwd_cb().

Function Documentation

◆ jwt_decode()

int jwt_decode	(	jwt_t **	jwt,
		const char *	token,
		const unsigned char *	key,
		int	key_len )

Decode an existing JWT and allocate a new JWT object from it.

Decodes a JWT string and verifies the signature (if one is supplied). If no signature is used (JWS, alg="none") or key is NULL, then no validation is done other than formatting. It is not suggested to use this on a string that has a signature without passing the key to verify it. If the JWT is encrypted and no key is supplied, an error is returned.

Parameters

jwt	Pointer to a JWT object pointer. Will be allocated on success.
token	Pointer to a valid JWT string, nul terminated.
key	Pointer to the key for validating the JWT signature or for decrypting the token or NULL if no validation is to be performed.
key_len	The length of the above key.

Returns: 0 on success, valid errno otherwise.

Remarks: If a key is supplied, the token must pass sig check or decrypt for it to be parsed without error. If no key is supplied, then a non-encrypted token will be parsed without any checks for a valid signature, however, standard validation of the token is still performed.

Warning: You should not assume that decoding means your JWT is verified. You should check the resulting jwt_t for proper algorithm and grants.

◆ jwt_decode_2()

int jwt_decode_2	(	jwt_t **	jwt,
		const char *	token,
		jwt_key_p_t	key_provider )

Like jwt_decode(), but the key will be obtained via the key provider.

Key providers may use all sorts of key management techniques, e.g. can check the "kid" header parameter or download the key pointed to in "x5u"

Parameters

jwt	Pointer to a JWT object pointer. Will be allocated on success.
token	Pointer to a valid JWT string, null terminated.
key_provider	Pointer to a function that will obtain the key for the given JWT. Returns 0 on success or any other value on failure. In the case of an error, the same error value will be returned to the caller.

Returns: 0 on success, valid errno otherwise.

Remarks: See jwt_decode()

◆ jwt_dup()

jwt_t * jwt_dup ( jwt_t * jwt )

Duplicate an existing JWT object.

Copies all grants and algorithm specific bits to a new JWT object.

Parameters

jwt	Pointer to a JWT object.

Returns: A new object on success, NULL on error with errno set appropriately.

◆ jwt_free()

void jwt_free ( jwt_t * jwt )

Free a JWT object and any other resources it is using.

After calling, the JWT object referenced will no longer be valid and its memory will be freed.

Parameters

jwt	Pointer to a JWT object previously created with jwt_new() or jwt_decode().

◆ jwt_new()

int jwt_new ( jwt_t ** jwt )

Allocate a new, empty, JWT object.

This is used to create a new object for a JWT. After you have finished with the object, use jwt_free() to clean up the memory used by it.

Parameters

jwt	Pointer to a JWT object pointer. Will be allocated on success.

Returns: 0 on success, valid errno otherwise.