JWK

JSON Web Keys (RFC 7517) More...

Functions
bool	jose_jwk_gen (jose_cfg_t *cfg, json_t *jwk)
	Generates a new JWK. More...
bool	jose_jwk_pub (jose_cfg_t *cfg, json_t *jwk)
	Removes all private key material from a JWK. More...
bool	jose_jwk_prm (jose_cfg_t *cfg, const json_t *jwk, bool req, const char *op)
	Determines if an operation is permitted for a JWK. More...
json_t *	jose_jwk_thp (jose_cfg_t *cfg, const json_t *jwk, const char *alg)
	Calculates the thumbprint of a JWK as a URL-safe Base64 encoded JSON string. More...
size_t	jose_jwk_thp_buf (jose_cfg_t *cfg, const json_t *jwk, const char *alg, uint8_t *thp, size_t len)
	Calculates the thumbprint of a JWK. More...
json_t *	jose_jwk_exc (jose_cfg_t *cfg, const json_t *prv, const json_t *pub)
	Perform a key exchange. More...

Detailed Description

JSON Web Keys (RFC 7517)

A JSON Web Key (JWS) is a standard data format for expresing cryptographic keys in JSON.

See also

https://tools.ietf.org/html/rfc7517

https://tools.ietf.org/html/rfc7638

Function Documentation

jose_jwk_gen()

bool jose_jwk_gen	(	jose_cfg_t *	cfg,
		json_t *	jwk
	)

Generates a new JWK.

The JWK is generated using hints from the input in exactly the same format as you would find in the output. For example, the most common way to generate a key is to specify the algorithm you'd like to use the key with. For example (error handling omitted):

json_t *gen(void) {
    json_auto_t *jwk = json_pack("{s:s}", "alg", "ES256");
    jose_jwk_gen(NULL, jwk);
    return json_incref(jwk);
}

This method is preferred because other metadata can be inferred from the algorithm name, such as the key usage. Additionally, the algorithm metadata can be used to automatically generate correct headers when creating signatures (JWS) or encryptions (JWE). Thus, you should always default to creating keys by their algorithm usage.

However, should your requirements differ, you can also generate a key using raw parameters (again, error handling omitted):

json_t *gen(void) {
    json_auto_t *jwk = json_pack("{s:s,s:s}", "kty", "EC", "crv", "P-256");
    jose_jwk_gen(NULL, jwk);
    return json_incref(jwk);
}

json_t *gen(void) {
    json_auto_t *jwk = json_pack("{s:s,s:i}", "kty", "RSA", "bits", 2048);
    jose_jwk_gen(NULL, jwk);
    return json_incref(jwk);
}

json_t *gen(void) {
    json_auto_t *jwk = json_pack("{s:s,s:i}", "kty", "oct", "bytes", 32);
    jose_jwk_gen(NULL, jwk);
    return json_incref(jwk);
}

In this case, "bits" and "bytes" will be removed from the final output.

See also

https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms

Parameters

cfg	The configuration context (optional).
jwk	The JWK to generate.

Returns

On success, true. Otherwise, false.

jose_jwk_pub()

bool jose_jwk_pub	(	jose_cfg_t *	cfg,
		json_t *	jwk
	)

Removes all private key material from a JWK.

In addition, this function will remove any key operations from the key_ops JWK property (if present) that apply only to the private key.

This function should be used before exporting keys to third parties.

Parameters

cfg	The configuration context (optional).
jwk	The JWK to remove private keys from.

Returns

On success, true. Otherwise, false.

jose_jwk_prm()

bool jose_jwk_prm	(	jose_cfg_t *	cfg,
		const json_t *	jwk,
		bool	req,
		const char *	op
	)

Determines if an operation is permitted for a JWK.

The operation to be confirmed (op) is always specified according to the syntax of the "key_ops" JWK property, even when the "use" property is defined on the JWK.

This function has two modes of operation. If req is false, then JWKs which do not have any key use metadata will be approved for this operation. However, if req is true then this metadata will be required for approval.

Parameters

cfg	The configuration context (optional).
jwk	The JWK from which to remove private keys.
req	Whether JWK key use metadata is required or not.
op	The opperation to seek approval for.

Returns

When the JWK is approved, true. Otherwise, false.

jose_jwk_thp()

json_t* jose_jwk_thp	(	jose_cfg_t *	cfg,
		const json_t *	jwk,
		const char *	alg
	)

Calculates the thumbprint of a JWK as a URL-safe Base64 encoded JSON string.

This function is a thin wrapper around jose_jwk_thp_buf().

See also

jose_jwk_thp_buf()

Parameters

cfg	The configuration context (optional).
jwk	The JWK to calculate the thumbprint for.
alg	The hash algorithm to use.

Returns

On success, a newly-allocated JSON string. Otherwise, NULL.

jose_jwk_thp_buf()

size_t jose_jwk_thp_buf	(	jose_cfg_t *	cfg,
		const json_t *	jwk,
		const char *	alg,
		uint8_t *	thp,
		size_t	len
	)

Calculates the thumbprint of a JWK.

This function calculates the thumbprint of a JWK according to the method defined by RFC 7638.

If thp is NULL, this function returns the size of the buffer required for the thumbprint output.

See also

https://tools.ietf.org/html/rfc7638

Parameters

cfg	The configuration context (optional).
jwk	The JWK to calculate the thumbprint for.
alg	The hash algorithm to use.
thp	The output hash buffer.
len	The size of the output hash buffer.

Returns

On success, the number of bytes written. Otherwise, SIZE_MAX.

jose_jwk_exc()

json_t* jose_jwk_exc	(	jose_cfg_t *	cfg,
		const json_t *	prv,
		const json_t *	pub
	)

Perform a key exchange.

The only currently implemented algorithm is ECDH.

Parameters

cfg	The configuration context (optional).
prv	The private JWK.
pub	The public JWK.

Returns

On success, the JWK result of the key exchange. Otherwise, NULL.