JWK Library

A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key pair or individual public/private keys. The exact structure of JWK-JSON-objects is specified in RFC-7517.

JWKs are heavily used in a lot of web-based protocols such as Automatic Certificate Management Environment (ACME) or JSON Web Tokens (JWT).

File information

File	common/ilib/jwk.h
Overview
Classes	jwk
Defines	JSON_ID_ROOT JSON_ID_NONE
Examples	Encoding Decoding

Overview

The jwk class can be used for encoding and decoding public/private keys to/from JSON messages in JWK format. A JWK typically looks like this:

{
    "kty": "EC,"
    "crv": "P-256,"
    "x":   "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU,"
    "y":   "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0,"
    "d":   "jpsQnnGQmL-YBIffH1136cspYG6-0iY7X1fCE9-E9LI,"
    "alg": "ES256"
}

In this case the P256 elliptic curve is used and 'd' is the private key, 'x' and 'y' compose the public key. The 'alg' attribute specifies the used algorithm and is optional.

Decoding is usually done like that:

// JWK encoded in JSON string
char msg[1000] = "<Insert JSON object from above>";

// Decode JWK object from JSON string
jwk keys;
keys.decode(msg);

// No we can access the elements
auto kty = keys.kty;
auto crv = keys.crv;
auto d   = keys.params.p256.d;

There are different ways to encode public/private keys to JWK-JSON-objects.

// Encode JWK to string
keys.encode(msg);               // Encode public and private key
keys.encode_public_key(msg);    // Encode public key only
keys.encode_private_key(msg);   // Encode private key only

For better integration with innovaphone's json_io library, there are also additional overloads for the encode/decode methods. This way JWKs can not only be (de-)serialized from strings, but also from/to json_io objects.

// Append JWK to existing json structure
json_io json(msg);
word json_parent_elem = json.get_object();
keys.encode(&json, json_parent_elem, "jwk");
keys.encode_public_key(&json, json_parent_elem, "jwk-pub");
keys.encode_private_key(&json, json_parent_elem, "jwk-priv");
json.encode();

JWK objects can be used to sign/verify messages.

// Sign message
const char* msg2 = "Hello World";
char* signature = (char*)alloca(keys.getSignatureSize()));
keys.sign(signature, msg2, strlen(msg2));                   // Requires private key to be set

// Verify message
bool valid = keys.verify(signature, msg2, strlen(msg2));    // Requires public key to be set

Additionally we can generate "random" key pairs

keys.gen_es256_keys(); // Initializes JWK object 'keys' with a set of ES256 public/private keys.

JWK Library

File information

Overview

Classes

Public functions

Data types