Clavem

Verify an Ed25519 license token offline in a JUCE plugin

JUCE 9.0.6 has RSA keys and hashes but no Ed25519, so add Monocypher to your plugin target. Split the token, turn base64url into standard base64, check the signature over "sgt1.<payload>", then apply the five claim checks.

Add Monocypher to the plugin target

Monocypher is two C files, licensed BSD-2-Clause or CC0. Copy monocypher.c, monocypher.h and the optional monocypher-ed25519.c and .h into ThirdParty/monocypher/. Use the Ed25519 variant from the optional files: the default signatures in monocypher.c use BLAKE2b and will not verify a standard Ed25519 signature.

project(Inkwell VERSION 1.0.0 LANGUAGES C CXX)   # C must be enabled for the .c files

target_sources(Inkwell PRIVATE
    ThirdParty/monocypher/monocypher.c
    ThirdParty/monocypher/monocypher-ed25519.c)
target_include_directories(Inkwell PRIVATE ThirdParty/monocypher)
target_link_libraries(Inkwell PRIVATE juce::juce_cryptography)   # only for the optional kh check
set_target_properties(Inkwell PROPERTIES C_VISIBILITY_PRESET hidden CXX_VISIBILITY_PRESET hidden)   # plugins share a host process

If you build with Projucer, add the four files to the project and the folder to the header search paths.

The verifier

#include <juce_core/juce_core.h>
#include <juce_cryptography/juce_cryptography.h>
#include <optional>
#include "monocypher.h"
#include "monocypher-ed25519.h"

struct Claims
{
    int version = 0;
    juce::int64 pid = 0, iat = 0, exp = 0, refreshBy = 0;
    bool valid = false, hasExp = false;
    juce::String kh;
};

/** Clavem sends base64url without padding. juce::Base64 reads the standard alphabet. */
inline bool decodeBase64Url (const juce::String& text, juce::MemoryBlock& out)
{
    auto standard = text.replaceCharacter ('-', '+').replaceCharacter ('_', '/');
    while (standard.length() % 4 != 0)
        standard << "=";

    juce::MemoryOutputStream stream (out, false);
    return juce::Base64::convertFromBase64 (stream, standard);
}

inline std::optional<Claims> verifyToken (const juce::String& token, const juce::String& publicKey)
{
    const auto parts = juce::StringArray::fromTokens (token, ".", "");   // keeps empty parts
    if (parts.size() != 3 || parts[0] != "sgt1")
        return std::nullopt;

    juce::MemoryBlock key, signature, body;
    if (! decodeBase64Url (publicKey, key) || ! decodeBase64Url (parts[2], signature) || ! decodeBase64Url (parts[1], body)
        || key.getSize() != 32 || signature.getSize() != 64)
        return std::nullopt;

    // The signed text is "sgt1.<payload>", exactly as received.
    const auto signedText = parts[0] + "." + parts[1];
    if (crypto_ed25519_check (static_cast<const uint8_t*> (signature.getData()),
                              static_cast<const uint8_t*> (key.getData()),
                              reinterpret_cast<const uint8_t*> (signedText.toRawUTF8()),
                              signedText.getNumBytesAsUTF8()) != 0)
        return std::nullopt;

    const auto json = juce::JSON::parse (juce::String::fromUTF8 (static_cast<const char*> (body.getData()), (int) body.getSize()));
    if (! json.isObject())
        return std::nullopt;

    Claims c;
    c.version = json["v"];
    c.pid = (juce::int64) json["pid"];
    c.valid = (bool) json["valid"];
    c.iat = (juce::int64) json["iat"];
    c.refreshBy = (juce::int64) json["refresh_by"];
    c.kh = json["kh"].toString();
    c.hasExp = json.hasProperty ("exp");
    c.exp = c.hasExp ? (juce::int64) json["exp"] : 0;
    return c;
}

/** The checks from the offline verification docs. */
inline bool isLicensed (const std::optional<Claims>& c, juce::int64 productId, juce::int64 nowSeconds)
{
    return c.has_value() && c->version == 1 && c->pid == productId && c->valid
        && (! c->hasExp || c->exp > nowSeconds) && c->refreshBy > nowSeconds;
}

Pass juce::Time::currentTimeMillis() / 1000 as nowSeconds. The optional kh check normalizes the typed key as the offline docs describe, then compares the first 16 hex characters of juce::SHA256 over its UTF-8 bytes with claims.kh.

What I ran

I compiled this against JUCE 9.0.6 juce_core and juce_cryptography on macOS with Monocypher 4.0.3, and ran it on tokens signed with a throwaway key pair in Clavem’s token format. The real demo product’s public key is not available to me, so I decoded the demo token’s payload but could not verify its signature.

Token Signature Licensed Reason
good valid yes All checks pass
tampered invalid no pid edited after signing
stale valid no refresh_by has passed
expiredLicense valid no valid is false
otherProduct valid no pid is not yours
wrongVersion valid no v is 2
pastExp valid no exp is in the past
wrongKey invalid no Signed by another product’s key

Four malformed inputs (not-a-token, four parts, a short public key, an empty payload) all came back empty. The kh check matched the demo key S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8 against the demo token’s kh of 7e0e4148136b6dae, also when the key was typed in lowercase with spaces, and rejected a different key.

JUCE traps

  • Base64. juce::Base64 reads only the standard alphabet, so convert - and _ and add padding first. It rejected input with characters outside the alphabet, and it accepted a signature with an extra trailing =, so do not count on it to reject malformed padding.
  • Bytes, not characters. Pass getNumBytesAsUTF8() to the signature check. length() counts characters and would break on any non-ASCII text.
  • fromTokens. In 9.0.6 it kept the empty middle of sgt1..sig and returned three parts, so the size() == 3 test holds and an empty payload fails later, at the signature or the JSON step.
  • Numbers in var. JSON integers arrive as var. Cast to juce::int64, as above, so Unix seconds do not overflow an int after 2038.
  • Link language. LANGUAGES C CXX is easy to forget in a JUCE project that was created with C++ only.
  • Clock set back. Store the highest iat you have seen beside the token. If now + 300 < maxIat, require an online check before trusting it.

When refresh_by passes, the validation client asks the server again. Verification needs no network, and a shipped public key can be read by anyone, which is fine because it only verifies.

Compared with JUCE’s own online authentication

JUCE includes classes for online product authentication. Their subclasses supply an RSA public key to authenticate the server’s responses, and one implementation talks to the Tracktion Marketplace. That fits a store that speaks that exchange. Clavem’s tokens use Ed25519, so the verifier above is separate.

Doing this with Clavem

Each product has its own Ed25519 key pair. The public key is on the product page, and the token fields are in the offline verification docs.

Questions

Why not use JUCE's RSA classes?

Clavem signs tokens with Ed25519, a different algorithm. The juce_cryptography module has RSAKey, Blowfish and hashes such as SHA256, and I found no Ed25519 in the JUCE 9.0.6 modules.

Does the audio thread need to verify the token?

No. Verify once on the background thread from the validation guide and publish a state in an atomic. Verification is quick, but processBlock should only read a flag.

Sources

  1. Monocypher project page, licence and API (checked November 2026)
  2. JUCE documentation, juce::TracktionMarketplaceStatus (checked November 2026)