Rhonabwy
Javascript Object Signing and Encryption (JOSE) library - JWK, JWKS, JWS, JWE and JWT
|
Rhonabwy library is made to manage JWK, JWKS, JWS, JWE and JWT according to their respective RFCs:
Rhonabwy is based on the following libraries and actively uses them:
When relevant, a function can accept or return GnuTLS or Jansson data. But if you're not using those in your application and prefer raw data, you can use the more agnostic functions.
Lots of functions in Rhonabwy library return an int value. The returned value can be one of the following:
If a function is successful, it will return RHN_OK
(0), otherwise an error code is returned.
It's recommended to use r_global_init
and r_global_close
at the beginning and at the end of your program to initialize and cleanup internal values and settings. This will make outgoing requests faster, especially if you use lots of them, and dispatch your memory allocation functions in curl and Jansson if you changed them. These functions are NOT thread-safe, so you must use them in a single thread context.
Usually, a log message is displayed to explain more specifically what happened on error. The log manager used is Yder. You can enable Yder log messages on the console with the following command at the beginning of your program:
Example of an error log message:
Go to Yder API Documentation for more details.
All typedefs managed by Rhonabwy use dedicated init and free functions. You must always use those functions to allocate or free resources manipulated by the library.
In addition, when a function return a char *
value, this value must be freed using the function r_free(void *)
.
And finally, all json_t *
returned values must be de allocated using json_decref(json_t *)
, see Jansson Documentation for more details.
The functions r_library_info_json_t()
and r_library_info_json_str()
return a JSON object that represents the signature and encryption algorithms supported, as well as the library version.
Example output:
When using r_jws_set_header_int_value
, r_jwe_set_header_int_value
, r_jwt_set_header_int_value
or r_jwt_set_claim_int_value
, the int value must be of type rhn_int_t
, which inner format depend on the architecture. It's recommended not to use an int
instead, or undefined behaviour may happen.
Likewise, the functions r_jws_get_header_int_value
, r_jwe_get_header_int_value
, r_jwt_get_header_int_value
or r_jwt_get_claim_int_value
, these functions will return a rhn_int_t
.
To use a rhn_int_t
in a printf-like function, you can use the macro RHONABWY_INTEGER_FORMAT
:
A JWK (JSON Web Key) is a format used to store and represent a cryptographic key in a JSON object.
Example of JWK:
The standard allows to store public and private keys for RSA and ECC algorithms, it also allows to store symmetric keys. In a JWK, every raw value is encoded in Base64Url format to fit in the JSON object without any issue.
A JWK is represented in Rhonabwy library using the type jwk_t *
.
Rhonabwy allows to import and export a JWK in the following formats:
const char *
json_t *
PEM
or DER
formatGnuTLS
structure of the following: gnutls_privkey_t
, gnutls_pubkey_t
or gnutls_x509_crt_t
(import only)If the imported JWK contains a x5u
property, the key or certificate will be downloaded at the given address. If so, you can give an additional parameter x5u_flag
which values can be:
R_FLAG_IGNORE_SERVER_CERTIFICATE
: ignore if web server certificate is invalidR_FLAG_FOLLOW_REDIRECT
: follow redirection if necessaryR_FLAG_IGNORE_REMOTE
: do not download remote key, but the function may return an errorThe values R_FLAG_IGNORE_SERVER_CERTIFICATE
and R_FLAG_FOLLOW_REDIRECT
can be merged: R_FLAG_IGNORE_SERVER_CERTIFICATE|R_FLAG_FOLLOW_REDIRECT
You can manipulate the JWK properties directly using the dedicated functions:
The function r_jwk_is_valid
will check the validity of a JWK, i.e. check if all the required properties are present and in the correct format. Note that this function is called each time an import is made.
You can use Rhonabwy to generate a random key pair for RSA, ECC or OKP algorithms. The jwk_t *
parameters must be initialized first.
The type
parameter can have one of the following values: R_KEY_TYPE_RSA
R_KEY_TYPE_EC
, R_KEY_TYPE_EDDSA
or R_KEY_TYPE_ECDH
. The bits
parameter specifies the length of the key. A RSA key must be at least 2048 bits, and the bits value allowed for an ECC key are 256, 384 or 512.
If the parameter kid
is used, the generated key kid property will have the kid specified, otherwise a kid
will be generated to identify the key pair.
A JWKS (JSON Web Key Set) is a format used to store and represent a set cryptographic key in a JSON object. A JWKS is always a JSON object containing the property "keys"
that will point to an array of JWK.
Example of JWKS:
In Rhonabwy library, you can manipulate the JWKS inside a JWKS by iteration or get a JWK by its kid.
You can also import a JWKS using a JSON object or an URL.
Finally, a JWT (JSON Web Token) is a JSON content signed and/or encrypted and serialized in a compact format that can be easily transferred in HTTP requests. Technically, a JWT is a JWS or a JWE which payload is a stringified JSON and has the property "type":"JWT"
in the header.
A JWT can be nested, which means signed and encrypted, in which case the payload is signed as a JWS first, then the serialized signed token is used as the payload in a JWE, or the opposite.
To set the values of the JWT (header, keys, payload, etc.), you can use the dedicated functions (see the documentation), or use the function r_jwt_set_properties
to set multiple properties at once. The option list MUST end with the option RHN_OPT_NONE
.
The available rhn_opt
and their following values for a jwt_t
are:
Example of usage for r_jwt_set_properties
:
The function int int r_jwt_validate_claims(jwt_t * jwt, ...)
will help you verify the validity of some claims in the JWT.
Claim types available
R_JWT_CLAIM_ISS
: claim "iss"
, values expected a string or NULL
to validate the presence of the claimR_JWT_CLAIM_SUB
: claim "sub"
, values expected a string or NULL
to validate the presence of the claimR_JWT_CLAIM_AUD
: claim "aud"
, values expected a string or NULL
to validate the presence of the claimR_JWT_CLAIM_EXP
: claim "exp"
, value expected R_JWT_CLAIM_NOW
or an positive integer value or R_JWT_CLAIM_PRESENT
to validate the presence of the claimR_JWT_CLAIM_NBF
: claim "nbf"
, value expected R_JWT_CLAIM_NOW
or an positive integer value or R_JWT_CLAIM_PRESENT
to validate the presence of the claimR_JWT_CLAIM_IAT
: claim "iat"
, value expected R_JWT_CLAIM_NOW
or an positive integer value or R_JWT_CLAIM_PRESENT
to validate the presence of the claimR_JWT_CLAIM_JTI
: claim "jti"
, values expected a string or NULL
to validate the presence of the claimR_JWT_CLAIM_STR
: the claim name specified must have the string value expected or NULL
to validate the presence of the claimR_JWT_CLAIM_INT
: the claim name specified must have the integer value expectedR_JWT_CLAIM_JSN
: the claim name specified must have the json_t * value expected or NULL
to validate the presence of the claimR_JWT_CLAIM_TYP
: header parameter "typ"
(type), values expected a string or NULL
to validate the presence of the header parameterR_JWT_CLAIM_CTY
: header parameter "cty"
(Content Type), values expected a string or NULL
to validate the presence of the header parameterFor example, the following code will check the jwt against the claim iss
has the value "https://example.com"
, the claim sub
has the value "client_1"
, the presence of the claim aud
, the claim exp
is after now, the claim nbf
is before now, the claim scope
has the value "scope1"
, the claim age
has the value 42
and the claim verified
has the JSON value true
:
Let's use the following JSON object in a JWT:
The JWT can be signed using the algorithm HS256
and the following key:
The signed JWT serialized will be:
The signed JWT above can be created with the following sample code:
The same payload can be encrypted and serialized in an encrypted JWT using RSA1_5
as key encryption algorithm and A128CBC-HS256
as content encryption algorithm.
The encrypted JWT of the payload above can be the following:
An encrypted JWT can be created with Rhonabwy using the following sample code:
A nested JWT can be created with Rhonabwy using the following sample code:
The functions r_jwt_parse
and r_jwt_parsen
will parse a serialized JWT. If public keys are present in the header, they will be added to the public keys list and can be used to verify the token signature.
JWT standard allows to add in the JWT header a public key in several forms:
jwk
: a public key in JWK formatjku
: an url to a JWK Setx5c
: an array of X509 certificatesx5u
: an url to a X509 certificateWhen using the functions r_jwt_parse
, r_jwt_parsen
, r_jwt_compact_parse
, r_jwt_compact_parsen
, r_jwt_parse_unsecure
, r_jwt_parsen_unsecure
, r_jwt_compact_parsen_unsecure
and r_jwt_compact_parse_unsecure
, by default, if a public key is mentionned in the header, it will be added to the jwt->jwks_pubkey
, so the signature verification will not need to specify a key. This can be dangerous if the token comes from a untrustworthy source and if the token isn't checked properly.
To simplify secure token parsing, you should use the functions r_jwt_advanced_parse[n]
:
The quick parsing functions can be used to parse a JWT in one line:
It's possible to use Rhonabwy for unsecured JWT, with the header alg:"none"
and an empty signature, using a dedicated set of functions: r_jwt_parse_unsecure
, r_jwt_parsen_unsecure
and r_jwt_serialize_signed_unsecure
, or using r_jwt_advanced_parse
with the parse_flags
value R_PARSE_UNSIGNED
set.
By default, the functions r_jwt_parse
and r_jwt_parsen
will return RHN_ERROR_INVALID
if the parsed JWT is unsigned. To parse any JWT, signed or unsigned, you must use the functions r_jwt_parse_unsecure
and r_jwt_parsen_unsecure
, or using r_jwt_advanced_parse
with the parse_flags
value R_PARSE_UNSIGNED
set.
Use the function r_jwt_serialize_signed_unsecure
to serialize an unsecured JWT.
The function r_jwt_verify_signature
will return RHN_ERROR_INVALID
if the JWT is unsecured.
It's not possible to serialize or parse a nested JWT with an unsecured signature.
A JWS (JSON Web Signature) is a content digitally signed and serialized in a compact or JSON format that can be easily transferred in HTTP requests.
A compact JWS has 3 elements serialized in base64url format and separated by a dot (.). The 3 elements are:
Its representation uses the following format:
BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Signature)
The signature is based on the following data:
BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload)
The algorithms supported by Rhonabwy are:
HS256
, HS384
, HS512
RS256
, RS384
, RS512
ES256
, ES384
, ES512
, ES256K
PS256
, PS384
, PS512
EDdSA
none
To set the values of the JWS (header, keys, payload, etc.), you can use the dedicated functions (see the documentation), or use the function r_jws_set_properties
to set multiple properties at once. The option list MUST end with the option RHN_OPT_NONE
.
The available rhn_opt
and their following values for a jws_t
are:
Example of usage for r_jws_set_properties
:
In this example, the payload used is the following message:
The JWS will be signed using HMAC with SHA256 algorithm, in this example, the signing process will use a key identified by the kid "1", therefore the header is the following:
The key used to sign the data is:
Finally, the complete representation of the JWS is the following:
The JWS above can be created with the following sample code:
The JWS above can be parsed and verified using the following sample code:
The functions r_jws_parse
, r_jws_parsen
, r_jws_compact_parse
and r_jws_compact_parsen
will parse a serialized JWS. If public keys are present in the header, they will be added to the public keys list and can be used to verify the token signature.
The header value "zip":"DEF"
is used to specify if the JWS payload is compressed using ZIP/Deflate algorithm. Rhonabwy will automatically compress or decompress the decrypted payload during serialization or parse process.
It's possible to use Rhonabwy for unsecured JWS, with the header alg:"none"
and an empty signature, using a dedicated set of functions: r_jws_parse_unsecure
, r_jws_parsen_unsecure
, r_jws_compact_parsen_unsecure
, r_jws_compact_parse_unsecure
and r_jws_serialize_unsecure
, or using r_jws_advanced_parse
with the parse_flags
value R_PARSE_UNSIGNED
set.
By default, the functions r_jws_parse
, r_jws_parsen
, r_jws_compact_parse
and r_jws_compact_parsen
will return RHN_ERROR_INVALID
if the parsed JWS is unsigned. To parse any JWS, signed or unsigned, you must use the functions r_jws_parse_unsecure
, r_jws_parsen_unsecure
, r_jws_compact_parsen_unsecure
and r_jws_compact_parse_unsecure
, or using r_jws_advanced_parse
with the parse_flags
value R_PARSE_UNSIGNED
set.
Use the function r_jws_serialize_unsecure
to serialize an unsecured JWS. By design, the functions r_jws_serialize_json_t
and r_jws_serialize_json_str
will return NULL with mode R_JSON_MODE_FLATTENED
on unsecured JWS.
JWS standard allows to add in the JWS header a public key in several forms:
jwk
: a public key in JWK formatjku
: an url to a JWK Setx5c
: an array of X509 certificatesx5u
: an url to a X509 certificateWhen using the functions r_jws_parse
, r_jws_parsen
, r_jws_compact_parse
, r_jws_compact_parsen
, r_jws_parse_unsecure
, r_jws_parsen_unsecure
, r_jws_compact_parsen_unsecure
and r_jws_compact_parse_unsecure
, by default, if a public key is mentionned in the header, it will be added to the jws->jwks_pubkey
, so the signature verification will not need to specify a key. This can be dangerous if the token comes from a untrustworthy source and if the token isn't checked properly.
To simplify secure token parsing, you should use the functions r_jws_advanced_parse[n]
:
The quick parsing functions can be used to parse a JWS in one line:
Signature verification is provided by the function r_jws_verify_signature
which has the following definition:
The function r_jws_verify_signature
will return RHN_ERROR_INVALID
if the JWS is unsecured.
A JWE (JSON Web Encryption) is an encrypted content serialized in a compact format that can be easily transferred in HTTP requests.
Basically the payload is encrypted using AES-CBC or AES-GCM and an Initialization Vector (IV), a authentication tag is generated to validate the decryption, and the AES key used to encrypt the payload is encrypted itself using a symmetric or asymmetric encryption algorithm.
The serialized token has the following format:
BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE Authentication Tag)
In Rhonabwy library, the supported algorithms are:
enc
) for JWE payload encryption: A128CBC-HS256
, A192CBC-HS384
, A256CBC-HS512
, A128GCM
, A2192GCM
, A256GCM
RSA1_5
(RSAES-PKCS1-v1_5), RSA-OAEP
, RSA-OAEP-256
, A128KW
, A192KW
, A256KW
, dir
(Direct use of a shared symmetric key), A128GCMKW
, A192GCMKW
, A256GCMKW
, ECDH-ES
, ECDH-ES+A128KW
, ECDH-ES+A192KW
, ECDH-ES+A256KW
, PBES2-HS384+A192KW
and PBES2-HS512+A256KW
, PBES2-HS256+A128KW
If you don't specify a Content Encryption Key or an Initialization Vector before the serialization, Rhonabwy will automatically generate one or the other or both depending on the algorithm specified.
To set the values of the JWE (header, keys, payload, etc.), you can use the dedicated functions (see the documentation), or use the function r_jwe_set_properties
to set multiple properties at once. The option list MUST end with the option RHN_OPT_NONE
.
The available rhn_opt
and their following values for a jwe_t
are:
Example of usage for r_jwe_set_properties
:
In this example, the payload used is the following message:
The RSA private key associated to this token is:
The encryption algorithm used is A128CBC-HS256
and the cryptographic algorithm to encrypt the key is RSA1_5
Finally, the complete representation of the JWE is:
The JWE above can be created with the following sample code:
The header value "zip":"DEF"
is used to specify if the JWE payload is compressed using ZIP/Deflate algorithm. Rhonabwy will automatically compress or decompress the decrypted payload during encryption or decryption process.
The JWE above can be parsed and verified using the following sample code:
The ECDH-ES algorithm requires an ECC or ECDH public key for the encryption. The RFC specifies `"A new ephemeral public key value MUST be generated for each key agreement operation.", so an ephemeral key is genererated on each encryption.
You can specify the ephemeral key to use though, by setting an encryption key to the JWE before generating the token. The responsibilty not to reuse the same ephemeral key is yours then.
Example with a specified ephemeral key:
Rhonabwy supports serializing and parsing tokens in JSON format, see JWE JSON Serialization and JWS JSON Serialization.
To serialize a JWS in JSON format, you must use the functions r_jws_serialize_json_t
or r_jws_serialize_json_str
, the parameter mode
must have the value R_JSON_MODE_GENERAL
to serialize in general format (allows multiple signatures), or R_JSON_MODE_FLATTENED
to serialize in flattened format.
To parse a JWS in JSON format, you can either use r_jws_parse_json_str
, r_jws_parsen_json_str
or r_jws_parse_json_t
when you know the token is in JSON format, or you can use r_jws_parse
or r_jws_parsen
.
If the token is in general JSON format and has multiple signatures, the function r_jws_verify_signature
will return RHN_OK
if one of the signatures is verified by the public key specified or one of the public keys added to its public JWKS.
To serialize a JWE in JSON format, you must use the functions r_jwe_serialize_json_t
or r_jwe_serialize_json_str
, the parameter mode
must have the value R_JSON_MODE_GENERAL
to serialize in general format (allows multiple key encryption), or R_JSON_MODE_FLATTENED
to serialize in flattened format.
To parse a JWE in JSON format, you can either use r_jwe_parse_json_str
, r_jwe_parsen_json_str
or r_jwe_parse_json_t
when you know the token is in JSON format, or you can use r_jwe_parse
or r_jwe_parsen
.
If the token is in general JSON format and has multiple key encryption, the function r_jwe_decrypt
will decrypt the payload and return RHN_OK
if one of the recipients content is correctly decrypted using a specified private key or one of the private key added to its private JWKS.
The quick parsing functions can be used to parse a JWE in one line: