What you add to the module
Download Monocypher (4.0.3 at the time of writing) and copy monocypher.c, monocypher.h and the optional monocypher-ed25519.c and .h into Source/MyGame/ThirdParty/Monocypher/. The Ed25519 variant lives in that optional file: the default signatures in monocypher.c use BLAKE2b and will not verify a standard Ed25519 signature. Monocypher is licensed BSD-2-Clause or CC0, your choice.
// MyGame.Build.cs
PublicIncludePaths.Add(Path.Combine(ModuleDirectory, "ThirdParty", "Monocypher"));
I did not check how every Unreal toolchain treats .c files in a module. Monocypher also compiles as C++ (I built it with clang++ -x c++ -Wall without errors), so renaming the two files to .cpp is a safe fallback.
The verifier
// ClavemToken.h
#pragma once
#include "CoreMinimal.h"
#include "Dom/JsonObject.h"
#include "Misc/Base64.h"
#include "Serialization/JsonSerializer.h"
#include "monocypher.h"
#include "monocypher-ed25519.h"
namespace Clavem
{
const FString PublicKey = TEXT("YOUR_PUBLIC_KEY"); // from your product page: 32 bytes, base64url
constexpr int64 ProductId = 75; // from your product page
struct FClaims { int32 V = 0; int64 Pid = 0, Iat = 0, Exp = 0, RefreshBy = 0; bool bValid = false, bHasExp = false; };
// Clavem sends base64url without padding. FBase64 in Standard mode wants "+" "/" and padding.
inline bool DecodeBase64Url(const FString& In, TArray<uint8>& Out)
{
FString S = In.Replace(TEXT("-"), TEXT("+")).Replace(TEXT("_"), TEXT("/"));
while (S.Len() % 4 != 0) { S.AppendChar(TEXT('=')); }
return FBase64::Decode(S, Out, EBase64Mode::Standard);
}
inline TOptional<FClaims> VerifyToken(const FString& Token, const FString& Key64)
{
TArray<FString> Parts;
Token.ParseIntoArray(Parts, TEXT("."), /*InCullEmpty=*/false); // the default, true, drops empty parts
if (Parts.Num() != 3 || Parts[0] != TEXT("sgt1")) { return {}; }
TArray<uint8> Key, Sig, Body;
if (!DecodeBase64Url(Key64, Key) || !DecodeBase64Url(Parts[2], Sig) || !DecodeBase64Url(Parts[1], Body)
|| Key.Num() != 32 || Sig.Num() != 64)
{
return {};
}
// The signed text is "sgt1.<payload>", exactly as received.
const FTCHARToUTF8 Signed(*(Parts[0] + TEXT(".") + Parts[1]));
if (crypto_ed25519_check(Sig.GetData(), Key.GetData(), reinterpret_cast<const uint8*>(Signed.Get()), Signed.Length()) != 0)
{
return {};
}
const FUTF8ToTCHAR Text(reinterpret_cast<const ANSICHAR*>(Body.GetData()), Body.Num());
TSharedPtr<FJsonObject> Json;
if (!FJsonSerializer::Deserialize(TJsonReaderFactory<>::Create(FString(Text.Length(), Text.Get())), Json) || !Json.IsValid())
{
return {};
}
FClaims C;
double N = 0; // FJsonObject reads every number as a double: exact for ids and Unix seconds
if (Json->TryGetNumberField(TEXT("v"), N)) { C.V = static_cast<int32>(N); }
if (Json->TryGetNumberField(TEXT("pid"), N)) { C.Pid = static_cast<int64>(N); }
if (Json->TryGetNumberField(TEXT("iat"), N)) { C.Iat = static_cast<int64>(N); }
if (Json->TryGetNumberField(TEXT("refresh_by"), N)) { C.RefreshBy = static_cast<int64>(N); }
if ((C.bHasExp = Json->TryGetNumberField(TEXT("exp"), N))) { C.Exp = static_cast<int64>(N); }
Json->TryGetBoolField(TEXT("valid"), C.bValid);
return C;
}
/** The checks from the offline verification docs. Now is Unix seconds. */
inline bool IsLicensed(const TOptional<FClaims>& C, int64 Expected, int64 Now)
{
return C.IsSet() && C->V == 1 && C->Pid == Expected && C->bValid
&& (!C->bHasExp || C->Exp > Now) && C->RefreshBy > Now;
}
}
Call it with Clavem::IsLicensed(Clavem::VerifyToken(Saved.Token, Clavem::PublicKey), Clavem::ProductId, FDateTime::UtcNow().ToUnixTimestamp()).
What I ran
The Unreal types in that header were not compiled. I ran the same steps as a plain C++ port (own base64url handling, a split that keeps empty parts, the same crypto_ed25519_check call, the same checks) against tokens signed with a throwaway key pair in Clavem’s token format. The real demo product’s public key is not available, so the demo token’s signature could not be checked.
| 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 |
Unreal-specific traps
ParseIntoArrayculls empty strings by default.sgt1..sigwould come back as two parts. The port showed 2 parts with culling and 3 without. Passfalseand require exactly three.- Padding.
FBase64::Decodetakes a mode argument in the 5.0 reference. Standard mode expects the+/alphabet and padding, which is why the helper converts and pads first. I did not confirm how the URL-safe mode treats missing padding, so I avoided it. - UTF-8, not
TCHAR. The signature covers bytes.FTCHARToUTF8gives the ASCII bytes ofsgt1.<payload>; hashing the wide string would fail every token. - Do not log the token. The payload is signed, not encrypted, and holds the buyer’s email address. Unreal log files end up in bug reports.
- Clock set back. Keep the highest
iatyou have seen next to the token. IfNow + 300 < MaxIat, treat the clock as untrustworthy and require a validation; the five minutes absorb a slow clock. khis optional. In a game the key and token sit in the same file and the server already matched them, so the sample skips it. The offline docs describe how to compute it.
When refresh_by passes, call Validate() from the validation guide. A shipped public key can be read by anyone. That is intended: it only verifies.
Doing this with Clavem
Clavem signs each product’s tokens with its own Ed25519 key and shows the public half on the product page. The token fields and the 14-day refresh window are described in the offline verification docs.
Questions
Why not use OpenSSL from the engine for Ed25519?
I found no documented Ed25519 verify function in the Unreal API reference, and relying on bundled third-party libraries ties you to engine internals. A two-file C library that you ship yourself behaves the same on every target.
Can the token be forged by editing the game files?
A player cannot create a token the public key accepts. A player who patches your binary can still skip the check, as with any client-side check. The signature stops forged tokens, not removed checks.