[--product=] [--version=] [--key-file=] [--output=] * php deventitle-release.php verify --public-key= [--manifest=] * * The private key is read from the DEVENTITLE_SIGNING_KEY environment * variable or from --key-file, never from the command line (it would end up * in your shell history). Nothing is sent anywhere: upload the zip and the * .json manifest to DevEntitle yourself. * * Signature: Ed25519 over "||". Keys * are base64: a 32-byte public key and a 64-byte secret key, the same format * as libsodium and HUBCITY CRM's `wise:release-keys`. * * Needs PHP 7.2+ with the sodium extension. Licence: MIT. */ const KIT_VERSION = '1.0.0'; const VERSION_PATTERN = '/^\d+(\.\d+){1,3}(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/'; const SLUG_PATTERN = '/^[a-z0-9]+(?:-[a-z0-9]+)*$/'; if (PHP_SAPI !== 'cli') { exit("Run this from the command line.\n"); } if (! function_exists('sodium_crypto_sign_detached')) { fail('The PHP sodium extension is missing. Enable "extension=sodium" in php.ini, or use the Node version of the kit.'); } [$command, $args, $options] = parse_arguments(array_slice($argv, 1)); switch ($command) { case 'keygen': keygen(); break; case 'sign': sign($args[0] ?? fail('Which zip? Usage: sign '), $options); break; case 'verify': verify($args[0] ?? fail('Which zip? Usage: verify --public-key='), $options); break; default: usage(); exit($command === null || $command === 'help' || $command === '--help' ? 0 : 1); } function keygen(): void { $pair = sodium_crypto_sign_keypair(); out('DevEntitle Release Kit '.KIT_VERSION.': new Ed25519 signing keypair'); out(''); out('PUBLIC key: paste it into the product on DevEntitle (Edit product -> Release signing)'); out('and ship it inside your product, so installed copies can check updates:'); out(' '.base64_encode(sodium_crypto_sign_publickey($pair))); out(''); out('SECRET key: keep it offline (password manager, build machine only). Never commit it,'); out('never put it on a server, never upload it to DevEntitle. Anyone with it can sign releases.'); out(' '.base64_encode(sodium_crypto_sign_secretkey($pair))); out(''); out('Sign with: DEVENTITLE_SIGNING_KEY= php deventitle-release.php sign -.zip'); } function sign(string $zip, array $options): void { $zip = must_be_zip($zip); [$product, $version] = product_and_version($zip, $options); $secret = read_secret($options); $sha = hash_file('sha256', $zip); $signature = base64_encode(sodium_crypto_sign_detached(message($product, $version, $sha), $secret)); // Self-check with the public half, so a broken key is caught here. $public = sodium_crypto_sign_publickey_from_secretkey($secret); if (! sodium_crypto_sign_verify_detached(base64_decode($signature), message($product, $version, $sha), $public)) { fail('The signature did not verify with the key\'s own public half. The secret key is damaged.'); } $manifest = [ 'product' => $product, 'version' => $version, 'sha256' => $sha, 'size' => filesize($zip), 'signature' => $signature, 'built_at' => gmdate('Y-m-d\TH:i:s\Z'), ]; $output = $options['output'] ?? preg_replace('/\.zip$/i', '', $zip).'.json'; if (file_put_contents($output, json_encode($manifest, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES)."\n") === false) { fail("Could not write {$output}."); } out("Signed {$product} {$version}"); out(' SHA-256: '.$sha); out(' Public key: '.base64_encode($public).' (must match the one on DevEntitle)'); out(' Manifest: '.$output); out('Upload the zip and the manifest to DevEntitle (Releases -> Upload release).'); } function verify(string $zip, array $options): void { $zip = must_be_zip($zip); $manifestPath = $options['manifest'] ?? preg_replace('/\.zip$/i', '', $zip).'.json'; $manifest = is_file($manifestPath) ? json_decode((string) file_get_contents($manifestPath), true) : null; if (! is_array($manifest)) { fail("No readable manifest at {$manifestPath}. Pass --manifest=."); } $public = base64_decode(trim((string) ($options['public-key'] ?? '')), true); if ($public === false || strlen($public) !== SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES) { fail('Pass the product\'s public key: --public-key=.'); } [$product, $version] = product_and_version($zip, $options + array_filter(['product' => $manifest['product'] ?? null, 'version' => $manifest['version'] ?? null])); $sha = hash_file('sha256', $zip); $problems = []; if (! hash_equals(strtolower((string) ($manifest['sha256'] ?? '')), $sha)) { $problems[] = 'the SHA-256 in the manifest does not match the zip'; } if (isset($manifest['size']) && (int) $manifest['size'] !== filesize($zip)) { $problems[] = 'the size in the manifest does not match the zip'; } $signature = base64_decode((string) ($manifest['signature'] ?? ''), true); if ($signature === false || strlen($signature) !== SODIUM_CRYPTO_SIGN_BYTES || ! sodium_crypto_sign_verify_detached($signature, message($product, $version, $sha), $public)) { $problems[] = "the signature does not verify for \"{$product}|{$version}|\" with this public key"; } if ($problems) { fail('NOT valid: '.implode('; ', $problems).'.'); } out("Valid: {$product} {$version}, SHA-256 {$sha}, signature verified."); } function message(string $product, string $version, string $sha256): string { return $product.'|'.$version.'|'.strtolower($sha256); } function must_be_zip(string $path): string { if (! is_file($path)) { fail("{$path} does not exist."); } if (file_get_contents($path, false, null, 0, 2) !== 'PK') { fail("{$path} is not a zip archive."); } return $path; } /** --product / --version, or taken from a file name like acme-crm-1.2.0.zip */ function product_and_version(string $zip, array $options): array { $product = $options['product'] ?? null; $version = $options['version'] ?? null; if (($product === null || $version === null) && preg_match('/^([a-z0-9]+(?:-[a-z0-9]+)*)-(\d+(?:\.\d+){1,3}(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)\.zip$/', basename($zip), $m)) { $product = $product ?? $m[1]; $version = $version ?? $m[2]; } if ($product === null || ! preg_match(SLUG_PATTERN, $product)) { fail('Pass --product=, or name the zip -.zip.'); } if ($version === null || ! preg_match(VERSION_PATTERN, $version)) { fail('Pass --version=, or name the zip -.zip.'); } return [$product, $version]; } function read_secret(array $options): string { if (isset($options['key-file'])) { $value = @file_get_contents($options['key-file']); if ($value === false) { fail("Could not read {$options['key-file']}."); } } else { $value = getenv('DEVENTITLE_SIGNING_KEY'); if ($value === false || trim($value) === '') { fail('Set DEVENTITLE_SIGNING_KEY to your secret key, or pass --key-file=. (Run "keygen" once to create a keypair.)'); } } $secret = base64_decode(trim($value), true); if ($secret === false || strlen($secret) !== SODIUM_CRYPTO_SIGN_SECRETKEYBYTES) { fail('That is not a secret key from "keygen" (base64 of 64 bytes).'); } return $secret; } function parse_arguments(array $argv): array { $command = null; $args = []; $options = []; foreach ($argv as $arg) { if (strncmp($arg, '--', 2) === 0) { $parts = explode('=', substr($arg, 2), 2); $options[$parts[0]] = $parts[1] ?? true; } elseif ($command === null) { $command = $arg; } else { $args[] = $arg; } } return [$command, $args, $options]; } function usage(): void { out('DevEntitle Release Kit '.KIT_VERSION); out(''); out(' php deventitle-release.php keygen'); out(' php deventitle-release.php sign [--product=] [--version=] [--key-file=] [--output=]'); out(' php deventitle-release.php verify --public-key= [--manifest=]'); out(''); out('The secret key comes from DEVENTITLE_SIGNING_KEY or --key-file. Nothing is sent anywhere.'); } function out(string $line): void { fwrite(STDOUT, $line.PHP_EOL); } function fail(string $message): void { fwrite(STDERR, 'Error: '.$message.PHP_EOL); exit(1); }