Key and Signing Tool¶

About the key and signing tool¶

The key and signing tool (krkrsign) applies simple digital signatures to the data you distribute.

With digital signatures, you can check that a file was created by its legitimate author, and check files for tampering and corruption.

Currently, the following use these signatures:

File corruption check tool
The sigcheck plugin, which verifies signatures from the Kirikiri Z engine (Window.checkSignature)

Getting the tool¶

The key and signing tool is one of the Kirikiri Z standard tools.

When you build the engine in krkrz_dev, it is built along with it, and make install places krkrsign (krkrsign.exe on Windows) in the tools/ folder of the install destination
The source is in the krkrz_tools repository, and it can also be built on its own

The tool runs as a single executable (Windows / Linux / macOS).

Public and private keys¶

To use the key and signing tool, you first use it to create a pair of matching keys (a key pair): a public key and a private key.

Although they are called keys, they are really strings in the following format.

The public key may be made public; the private key must not be.

Signing uses the private key: the digital signature is generated with it.

Verifying the signature uses the public key. A private key and a public key always form a pair, and only signatures made with a given private key can be verified successfully with the public key paired with it.

If someone who does not know the private key signs with another private key, the signature cannot be verified with the legitimate public key. Since the private key cannot be derived from the public key, only the person who holds the private key can make a valid signature.

Note: The private key is not protected by a passphrase; it is saved as a plain text file. Handle the private key file with care and do not include it in distribution files, public version-control repositories, and the like. If you lose the private key, you can never again create signatures that verify with the same public key.

Note: Strictly speaking, when a public key is published, there should be a way to confirm that the public key itself is legitimate. If you cannot tell whether a public key is legitimate in the first place, a digital signature means much less. However, Kirikiri's key and signing tool does not go that far.

Note: Kirikiri's key and signing tool uses RSA (signatures are RSA-PSS over a SHA-256 hash).

The generated RSA key length is 1024 bits by default, the same as Kirikiri 2's key and signing tool. You can also choose 2048 / 3072 / 4096 bits.

The RSA public and private keys generated by Kirikiri's key and signing tool are compatible with PEM-format keys from other software, but using keys generated by other software, or using keys generated by this tool in other software, is not supported.

Compatibility with Kirikiri 2¶

Keys created with Kirikiri 2's key and signing tool can be used as is
Signatures created with Kirikiri 2's key and signing tool (.sig files and signatures embedded in an exe) can be verified with this tool
Signatures created with this tool can be verified with Kirikiri Z's sigcheck plugin

The command-line syntax has changed from the Kirikiri 2 tool (see "Using the command line" below).

Generating keys¶

Launching the key and signing tool opens its screen in a browser window (the screen is embedded in the executable, so no internet connection is needed). The screen is divided into three tabs, 「鍵の生成」 (Generate keys), 「署名」 (Sign), and 「署名の確認」 (Verify signatures), and 「鍵の生成」 is shown first.

鍵の長さ (Key length)
Selects the length of the key to generate. The default of 1024 bits (the same as the Kirikiri 2 tool) is normally fine.
「鍵を作る」 (Create keys) button
Click it to start generating a key pair. Longer keys can take a few seconds.

When generation finishes, the generated key pair appears in the 「公開鍵」 (Public key) and 「秘密鍵」 (Private key) fields below. You can also copy the contents of these fields. - Destination folder and file names
Specifies the folder and file names for saving the generated key pair. The default file names are public.txt for the public key and private.txt for the private key. - 「保存」 (Save) button
Saves the public key and private key to their respective files. If a file with the same name already exists, nothing is saved. To overwrite, check 「上書き」 (Overwrite).

Generating keys does not save them. Save them before closing the screen.

Signing¶

Click the 「署名」 (Sign) tab to show the signing screen.

秘密鍵 (Private key)
Specify the private key file. You can also choose it with the 「参照…」 (Browse...) button.
対象ファイル (Target files)
Specifies the files to sign. Write one file per line, or choose files with the 「追加…」 (Add...) button. You can sign multiple files at once. The 「クリア」 (Clear) button empties the list.
「署名する」 (Sign) button
Signs the target files. The results are listed per file.

The signature file is named after the target file with the extension .sig appended (for example, the signature of data.xp3 is data.xp3.sig). An existing .sig is overwritten.

Note: The Kirikiri Z engine executable has no "area for embedding a signature inside the exe" as in Kirikiri 2. The engine executable is therefore signed into «filename.sig» just like any other file. The file corruption check tool does not check an engine executable without a .sig, so be sure to sign the engine executable as well.

When you sign an exe that has an area for embedding a signature, such as a Kirikiri 2 engine executable, the signature is written into the exe and no .sig is created.

Note: Modifying a file after signing makes signature verification fail. Finish rewriting the exe's icon and resources, binding xp3, and so on before signing, and make signing the last step in building the distribution.

Verifying signatures¶

Click the 「署名の確認」 (Verify signatures) tab to show the verification screen.

公開鍵 (Public key)
Specify the public key file. You can also choose it with the 「参照…」 (Browse...) button.
対象ファイル (Target files)
Specifies the files whose signatures to verify. As with signing, write one file per line or add them with the 「追加…」 (Add...) button. You can verify multiple files at once.
「確認する」 (Verify) button
Verifies the signatures of the target files.

The result for each file is shown as 「正常」 (OK), 「破損」 (Corrupted), or 「エラー」 (Error). A file that has been modified, or whose signature was made with a different key or is damaged, is 「破損」; a file that cannot be verified, for example because it has no .sig, is 「エラー」.

Using the command line¶

With --cli, you can generate keys, sign, and verify signatures on the command line without opening the screen. This is convenient when combining the tool with tools such as make.

Use the following syntax. Options that take a value are written as --name=value.

krkrsign --cli keygen [--bits=1024] [--public=FILE] [--private=FILE] [--force]
krkrsign --cli sign   --key=<秘密鍵ファイル> <ファイル>...
krkrsign --cli verify --key=<公開鍵ファイル> <ファイル>...

keygen
Generates a key pair and saves the public key to the --public file (default public.txt) and the private key to the --private file (default private.txt). Choose the key length with --bits from 1024 (default) / 2048 / 3072 / 4096. Fails if the files already exist; add --force to overwrite.
sign
Signs the specified files with the private key given by --key. Multiple files can be signed in one call.
verify
Verifies the signatures of the specified files with the public key given by --key.

A key file is a file containing the key as text. The tool searches the file for the part from -----BEGIN ...----- to -----END ...-----, so you can also specify the file corruption check tool's settings file (.ini) as the public key.

--json outputs the results as JSON, and --quiet suppresses progress.

For example, to create keys and sign game.exe and data.xp3:

krkrsign --cli keygen
krkrsign --cli sign --key=private.txt game.exe data.xp3

After signing, the created signature files are shown like this:

署名  game.exe    game.exe.sig
署名  data.xp3    data.xp3.sig

To verify the signatures:

krkrsign --cli verify --key=public.txt game.exe data.xp3

For each file, 「正常」 (OK), 「破損」 (Corrupted), or 「エラー」 (Error) is shown.

The exit codes are as follows.

Exit code	Meaning
0	Success (for verify, all files are OK)
1	For verify, some files are corrupted
2	Failure (the key cannot be read, a file cannot be read or written, a .sig is missing, and so on)

Note: The Kirikiri 2 tool's syntax krkrsign -sign "対象ファイル名" "秘密鍵ファイル名" (target file, private key file) no longer works. Rewrite it as krkrsign --cli sign --key=秘密鍵ファイル名対象ファイル名.

For options common to all tools (--help and others), see Standard Tools.

Signature file (.sig) format¶

A signature file is a text file whose first line is -- SIGNATURE - SHA256/PSS/RSA --, followed by lines containing the signature in Base64 (wrapped every 64 characters). The signature is an RSA-PSS signature over the SHA-256 hash of the whole file.

For a Kirikiri 2 exe that has a signature area, a string in the same format is written into the signature area inside the exe. In that case, the embedded areas in the exe, including the signature area, are excluded from the hash calculation.

Verifying signatures in the Kirikiri Z engine¶

With the sigcheck plugin, you can verify signatures from within your game. For example, you can use it to confirm that a file downloaded from the network is legitimate.

When you start verification with Window.checkSignature(filename, publicKey, userData), it runs in the background, and the result is reported on completion through the onCheckSignatureDone event (1 = success, 0 = failure, -1 = canceled, -2 = error). Files with a .sig are verified using the .sig.

Note: A signature made with a different key or a damaged signature is shown as 「破損」 (Corrupted) in the key and signing tool, but is reported as «error (-2)» by the sigcheck plugin.