header.h File Reference

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

#include <stdbool.h>
#include "cjose/error.h"

Go to the source code of this file.

Typedefs
typedef struct json_t	cjose_header_t

Functions
cjose_header_t *	cjose_header_new (cjose_err *err)
cjose_header_t *	cjose_header_retain (cjose_header_t *header)
void	cjose_header_release (cjose_header_t *header)
bool	cjose_header_set (cjose_header_t *header, const char *attr, const char *value, cjose_err *err)
const char *	cjose_header_get (cjose_header_t *header, const char *attr, cjose_err *err)
bool	cjose_header_set_raw (cjose_header_t *header, const char *attr, const char *value, cjose_err *err)
char *	cjose_header_get_raw (cjose_header_t *header, const char *attr, cjose_err *err)

Variables
const char *	CJOSE_HDR_ALG
const char *	CJOSE_HDR_ENC
const char *	CJOSE_HDR_CTY
const char *	CJOSE_HDR_KID
const char *	CJOSE_HDR_EPK
const char *	CJOSE_HDR_APU
const char *	CJOSE_HDR_APV
const char *	CJOSE_HDR_ALG_NONE
const char *	CJOSE_HDR_ALG_ECDH_ES
const char *	CJOSE_HDR_ALG_RSA_OAEP
const char *	CJOSE_HDR_ALG_RSA1_5
const char *	CJOSE_HDR_ALG_A128KW
const char *	CJOSE_HDR_ALG_A192KW
const char *	CJOSE_HDR_ALG_A256KW
const char *	CJOSE_HDR_ALG_PS256
const char *	CJOSE_HDR_ALG_PS384
const char *	CJOSE_HDR_ALG_PS512
const char *	CJOSE_HDR_ALG_RS256
const char *	CJOSE_HDR_ALG_RS384
const char *	CJOSE_HDR_ALG_RS512
const char *	CJOSE_HDR_ALG_HS256
const char *	CJOSE_HDR_ALG_HS384
const char *	CJOSE_HDR_ALG_HS512
const char *	CJOSE_HDR_ALG_ES256
const char *	CJOSE_HDR_ALG_ES384
const char *	CJOSE_HDR_ALG_ES512
const char *	CJOSE_HDR_ALG_DIR
const char *	CJOSE_HDR_ENC_A256GCM
const char *	CJOSE_HDR_ENC_A128CBC_HS256
const char *	CJOSE_HDR_ENC_A192CBC_HS384
const char *	CJOSE_HDR_ENC_A256CBC_HS512

Detailed Description

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

Typedef Documentation

cjose_header_t

typedef struct json_t cjose_header_t

An instance of a header object (used when creating JWE/JWS objects).

Function Documentation

cjose_header_get()

const char* cjose_header_get	(	cjose_header_t *	header,
		const char *	attr,
		cjose_err *	err
	)

Retrieves the value of the requested header attribute from the header object.

Parameters

header[in]	a header object.
attr[in]	the header attribute to be got.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns

a string containing the current value for the requested attribute. The value returned is a null terminated UTF-8 encoded string, or NULL if corresponding string header was not found. The returned value is read-only and must not be modified or freed by the user. It is valid as long as the corresponding cjose_header_t object is not released.

cjose_header_get_raw()

char* cjose_header_get_raw	(	cjose_header_t *	header,
		const char *	attr,
		cjose_err *	err
	)

Retrieves the raw value of the requested header attribute from the header object.

Parameters

header[in]	a header object.
attr[in]	the header attribute to be got.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns

a string containing the current JSON value for the requested attribute.

cjose_header_new()

cjose_header_t* cjose_header_new

(

cjose_err *

err

)

Instsantiates a new header object. Caller is responsible for subsequently releasing the object through cjose_header_release().

Parameters

err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns

a newly allocated header object, or NULL if an error occurs.

cjose_header_release()

void cjose_header_release

(

cjose_header_t *

header

)

Releases an existing header object. Callers must use this method to dispose of header rather than directly free'ing a cjose_header object.

Parameters

header[in]

the header object to be released.

cjose_header_retain()

cjose_header_t* cjose_header_retain

(

cjose_header_t *

header

)

Retains an existing header object. Callers must use this method if the header will be used past the scope it was created in (e.g., from a cjose_jws_t object).

Parameters

header[in]

the header object to be retained.

Returns

the retained header object

cjose_header_set()

bool cjose_header_set	(	cjose_header_t *	header,
		const char *	attr,
		const char *	value,
		cjose_err *	err
	)

Sets a header attribute on a header object. If that header was previously set, this will replace the previous value with the new one.

Parameters

header[in]	a previously instantiated header object.
attr[in]	the header attribute to be set.
value[in]	the value to assign to the header attribute.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns

true if header is successfully set.

cjose_header_set_raw()

bool cjose_header_set_raw	(	cjose_header_t *	header,
		const char *	attr,
		const char *	value,
		cjose_err *	err
	)

Sets a raw header attribute on a header object. If that header was previously set, this will replace the previous value with the new one. The input value must be a JSON serialized string. This function does not retain pointers to specified attribute or value.

Parameters

header[in]	a previously instantiated header object.
attr[in]	the header attribute to be set.
value[in]	the JSON value to assign to the header attribute. The value must be a valid JSON, and will be assigned as is.

Variable Documentation

CJOSE_HDR_ALG

const char* CJOSE_HDR_ALG

The JWE algorithm header attribute name.

CJOSE_HDR_ALG_A128KW

const char* CJOSE_HDR_ALG_A128KW

The JWE algorithm attribute value for A128KW, A192KW and A256KW.

CJOSE_HDR_ALG_DIR

const char* CJOSE_HDR_ALG_DIR

The JWE algorithm attribute value for "dir".

CJOSE_HDR_ALG_ECDH_ES

const char* CJOSE_HDR_ALG_ECDH_ES

The JWE algorithm attribute value of ECDH-ES.

CJOSE_HDR_ALG_ES256

const char* CJOSE_HDR_ALG_ES256

The JWS algorithm attribute values for ES256, ES384 and ES512.

CJOSE_HDR_ALG_HS256

const char* CJOSE_HDR_ALG_HS256

The JWS algorithm attribute values for HS256, HS384 and HS512.

CJOSE_HDR_ALG_NONE

const char* CJOSE_HDR_ALG_NONE

The JWA algorithm attribute value for none.

CJOSE_HDR_ALG_PS256

const char* CJOSE_HDR_ALG_PS256

The JWS algorithm attribute value for PS256, PS384 and PS512.

CJOSE_HDR_ALG_RS256

const char* CJOSE_HDR_ALG_RS256

The JWS algorithm attribute value for RS256, RS384 and RS512.

CJOSE_HDR_ALG_RSA1_5

const char* CJOSE_HDR_ALG_RSA1_5

The JWE algorithm attribute value for RSA1_5.

CJOSE_HDR_ALG_RSA_OAEP

const char* CJOSE_HDR_ALG_RSA_OAEP

The JWE algorithm attribute value for RSA-OAEP.

CJOSE_HDR_APU

const char* CJOSE_HDR_APU

For ECDH-ES algorithms, the PartyU and PartyV values

CJOSE_HDR_CTY

const char* CJOSE_HDR_CTY

The JWE "cty" header attribute.

CJOSE_HDR_ENC

const char* CJOSE_HDR_ENC

The JWE content encryption algorithm header attribute name.

CJOSE_HDR_ENC_A128CBC_HS256

const char* CJOSE_HDR_ENC_A128CBC_HS256

The JWE content encryption algorithm value for A128CBC-HS256, A192CBC-HS384 and A256CBC-HS512.

CJOSE_HDR_ENC_A256GCM

const char* CJOSE_HDR_ENC_A256GCM

The JWE content encryption algorithm value for A256GCM.

CJOSE_HDR_EPK

const char* CJOSE_HDR_EPK

The Jose "epk" header attribte.

CJOSE_HDR_KID

const char* CJOSE_HDR_KID

The Jose "kid" header attribute.