Clavem

Verify a Clavem license token offline in a WordPress plugin

Verify the token with sodium_crypto_sign_verify_detached, which WordPress provides on every supported PHP version through sodium_compat. Do it in the daily cron job, store the time until which the token is good, and let page views compare that stored time with time().

The token format and the checks are in the offline verification reference, which includes a PHP version. This page builds on it for WordPress. The design question is where the verification runs. If it runs on every page view, a host without the native sodium extension pays for pure-PHP elliptic-curve math each time. The answer is to verify when the license is refreshed, store what the result means as one timestamp, and compare that on page views. The call that fetches the token and the cron job are in license key validation in a WordPress plugin. The check logic was run in Swift, Rust, Python, C++ and Node against the same test tokens.

The verifier

/** Returns the decoded bytes, or false when the input is not valid base64url. */
function clavem_b64url_decode( string $value ) {
	$b64 = strtr( $value, '-_', '+/' );
	return base64_decode( $b64 . str_repeat( '=', ( 4 - strlen( $b64 ) % 4 ) % 4 ), true ); // true: strict
}

/**
 * Returns array( reason, claims ). reason is 'ok', 'malformed', 'bad-signature', 'wrong-product',
 * 'not-valid', 'expired', 'clock-set-back' or 'stale'. claims is null unless the signature was good.
 */
function clavem_check_token( string $token, string $public_key, int $product_id, int $highest_iat = 0, ?int $now = null ): array {
	$now   = $now ?? time(); // not current_time( 'timestamp' ): that one is shifted by the site's timezone
	$parts = explode( '.', $token );
	if ( 3 !== count( $parts ) || 'sgt1' !== $parts[0] ) {
		return array( 'malformed', null );
	}
	$key = clavem_b64url_decode( trim( $public_key ) );
	$sig = clavem_b64url_decode( $parts[2] );
	$raw = clavem_b64url_decode( $parts[1] );
	if ( false === $key || false === $sig || false === $raw
		|| SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES !== strlen( $key ) || SODIUM_CRYPTO_SIGN_BYTES !== strlen( $sig ) ) {
		return array( 'malformed', null ); // sodium throws on wrong lengths, so check them first
	}
	try {
		$good = sodium_crypto_sign_verify_detached( $sig, $parts[0] . '.' . $parts[1], $key ); // the text as received
	} catch ( SodiumException $e ) {
		return array( 'malformed', null );
	}
	if ( ! $good ) {
		return array( 'bad-signature', null );
	}
	$c = json_decode( $raw, true );
	if ( ! is_array( $c ) || 1 !== ( $c['v'] ?? null ) ) {
		return array( 'malformed', null );
	}
	if ( ( $c['pid'] ?? null ) !== $product_id ) {
		return array( 'wrong-product', $c );
	}
	if ( true !== ( $c['valid'] ?? false ) ) {
		return array( 'not-valid', $c );
	}
	if ( isset( $c['exp'] ) && $c['exp'] <= $now ) {
		return array( 'expired', $c );
	}
	if ( $now < $highest_iat ) {
		return array( 'clock-set-back', $c );
	}
	if ( ( $c['refresh_by'] ?? 0 ) <= $now ) {
		return array( 'stale', $c );
	}
	return array( 'ok', $c );
}

Only 'ok' should turn the paid features on, and 'stale' means validate online. Comparisons use !== and true !== on purpose. PHP’s loose == treats the string "false" and the number 0 in ways you do not want in a license check.

Verify rarely, compare often

The refresh job from the validation page calls the verifier, and on 'ok' stores two numbers: the token’s iat, for the clock guard, and the time until which the token is good. The first is the highest iat seen. The second is the earlier of exp, when present, and refresh_by:

function inkwell_apply_token( array $saved ): string {
	$highest = (int) get_option( 'inkwell_highest_iat', 0 );
	list( $reason, $c ) = clavem_check_token( $saved['token'], INKWELL_PUBLIC_KEY, INKWELL_PRODUCT_ID, $highest );
	if ( 'ok' !== $reason ) {
		update_option( 'inkwell_valid_until', 0, false );
		return 'stale' === $reason ? 'needs-network' : 'invalid';
	}
	update_option( 'inkwell_highest_iat', max( $highest, (int) $c['iat'] ), false );
	update_option( 'inkwell_valid_until', min( $c['exp'] ?? PHP_INT_MAX, $c['refresh_by'] ), false );
	return 'licensed';
}

/** Cheap enough for every request: one option read and a comparison. No crypto. */
function inkwell_is_licensed(): bool {
	return time() < (int) get_option( 'inkwell_valid_until', 0 );
}

A token that expires between two cron runs then stops working on time, not up to a day late. The online path sets the same value from the fresh token the API returns. On a host with the native sodium extension, verification takes a negligible time. On a host that falls back to sodium_compat, the pure-PHP version is slower, so measure it on a cheap shared host. Because it runs from cron and a settings save only, either case is fine.

Test results

The same logic, on test tokens signed with a throwaway key in the documented sgt1 format, in other languages. The PHP code should return the same:

Token Reason
Fresh ok
exp in 30 days ok
exp a minute ago expired
refresh_by 6 days ago stale
Issued for an expired license (valid: false) not-valid
Another product’s pid wrong-product
v is 2 malformed
Payload edited to a far-off exp, old signature bad-signature
Signed by another key bad-signature
The live demo token, with a different public key bad-signature
Two or four parts, sgt2 prefix, plain text malformed
Fresh token, 15 days later stale
Fresh token, clock behind a token already seen clock-set-back

The live demo token is real and decodes, but Clavem signed it with its own key, so a verifier with any other public key has to refuse it. Write a PHPUnit data provider with these rows, passing $now, and the 15-days-later case needs no waiting.

Traps in WordPress and PHP

  • time() and not current_time( 'timestamp' ). The second is offset by the site’s timezone. It is not a Unix timestamp.
  • 32-bit PHP. Its integers overflow in 2038, and json_decode returns a float for a number that does not fit. Timestamps are fine today, but test on your oldest supported build before you rely on the (int) casts.
  • base64_decode needs the strict flag. Without true it skips characters it does not know.
  • Network-activated multisite. Use get_site_option and update_site_option for these values, so one network shares one result.
  • The check is plugin source. A customer can edit it. Keep anything that must stay protected on your own server.

Where the token lives

The token is signed, not secret, so it needs integrity more than hiding. An option with autoload off is fine, and a changed byte fails the signature. The payload holds the buyer’s email in readable form, so keep it out of debug logs and out of any admin screen.

Doing this with Clavem

Each product has its own key pair. The public half is on the product page and in GET /v1/admin/products, and every activate and validate response carries a token signed with the private half. See the API reference for the endpoints.

Questions

Does WordPress include Ed25519 verification?

Through the sodium functions. PHP ships the sodium extension, and WordPress loads sodium_compat when it is missing, so sodium_crypto_sign_verify_detached is available. The compat version is plain PHP and slower, which is one reason to verify rarely.

Why not use current_time for the clock?

current_time with the timestamp type returns a value shifted by the site's timezone offset, so it is not a Unix timestamp. Tokens use real Unix seconds, so compare with time(), which is always UTC.

Can a customer edit the check out of my plugin?

Yes. A plugin is PHP source on their server, and anyone can edit it. The signature stops forged tokens and refresh_by stops old ones, but nothing stops a patched plugin. Plan for honest customers, and keep the server-side parts of your product on your own server.