jwtxx README

C++ library to work with JWT

Upgrading from 1.x

If you're upgrading from jwtxx 1.x, please see the Migration Guide for detailed instructions and examples.

Dependencies

• cmake - build system.
• jansson - JSON parser.
• openssl/libressl - cryptography.
• boost (optional) - unit tests.

Compilation and installation

$ mkdir build
$ cd build
$ cmake ..
$ make
$ make install

It will install everything in /usr/local by default. If you want to install with a different destdir:

$ make DESTDIR=/path/to/your/destdir install

It will automatically append usr/local to your destdir. So if you specify DESTDIR=foo you will result in the following directory structure:

foo/usr/local/bin
foo/usr/local/include
foo/usr/local/lib

If you want a custom install dir prefix use CMAKE_INSTALL_PREFIX at compile time:

$ cmake -DCMAKE_INSTALL_PREFIX=/your/prefix ..
$ make
$ make install

If you specify -DCMAKE_INSTALL_PREFIX=foo you will result in the following directory structure:

foo/bin
foo/include
foo/lib

Documentation

Supported algorithms

• none - no signature.
• HS256, HS384, HS512 - HMAC-based algorithms with SHA-256, SHA-384 and SHA-512 hash functions respectively. Use shared secret.
• RS256, RS384, RS512 - RSA-based algorithms with SHA-256, SHA-384 and SHA-512 hash functions respectively. Use PKI.
• ES256, ES384, ES512 - Algorithms based on elliptic curves digital signature with SHA-256, SHA-384 and SHA-512 hash functions respectively. Use PKI.

RSA and ECDSA keys should be in PEM format. Public keys can be in form of certificates.

Documentation:

• Library reference
• Migration guide (1.x to 2.x)

Examples

HS256

Key argument is a shared secret.

#include <jwtxx/jwt.h>
#include <jwtxx/ios.h>
 
#include <iostream>
 
using namespace JWTXX;
 
int main()
{
    // Create
    JWT jwt(Algorithm::HS256, {{"sub", Value("user")}, {"iss", Value("madf")}});
    auto token = jwt.token("secret-key");
 
    // Parse
    try
    {
        JWT jwt2(token, Key(Algorithm::HS256, "secret-key"));
        std::cout << "Algorithm: " << algToString(jwt2.alg()) << "\n"
                  << "Subject:   " << jwt2.claim("sub") << "\n"
                  << "Issuer:    " << jwt2.claim("iss") << std::endl;
    }
    catch (const JWT::Error& error)
    {
        std::cerr << "Error parsing token: " << error.what() << std::endl;
    }
 
    return 0;
}

RS256

Key argument is either a private key (when you create a token) or a public key (when you parse it).

#include <jwtxx/jwt.h>
#include <jwtxx/ios.h>
 
#include <iostream>
 
using namespace JWTXX;
 
int main()
{
    // Create
    JWT jwt(Algorithm::RS256, {{"sub", Value("user")}, {"iss", Value("madf")}});
    auto token = jwt.token("/path/to/private-key.pem");
 
    // Parse
    try
    {
        JWT jwt2(token, Key(Algorithm::RS256, "/path/to/public-key.pem"));
        std::cout << "Algorithm: " << algToString(jwt2.alg()) << "\n"
                  << "Subject:   " << jwt2.claim("sub") << "\n"
                  << "Issuer:    " << jwt2.claim("iss") << std::endl;
    }
    catch (const JWT::Error& error)
    {
        std::cerr << "Error parsing token: " << error.what() << std::endl;
    }
 
    return 0;
}

If many tokens are generated from the same key, it is better to reuse it. Key reuse will save I/O and PEM parsing and Key construction.

#include <jwtxx/jwt.h>
 
#include <iostream>
 
using namespace JWTXX;
 
int main()
{
    Key key(Algorithm::RS256, "/path/to/private-key.pem");
    auto token1 = JWT(key.alg(),  {{"sub", Value("user1")}, {"iss", Value("madf")}}).token(key);
    std::cout << "Token 1: " << token1 << "\n";
    auto token2 = JWT(key.alg(),  {{"sub", Value("user2")}, {"iss", Value("madf")}}).token(key);
    std::cout << "Token 2: " << token2 << "\n";
    auto token3 = JWT(key.alg(),  {{"sub", Value("user3")}, {"iss", Value("madf")}}).token(key);
    std::cout << "Token 3: " << token3 << "\n";
 
    return 0;
}

ES256

Essentially the same as RS256, but you need elliptic curve keys.

none

Key argument is not used. Token has no signature part.