frost-verify

A standalone command-line tool for verifying FROST signatures and generating test data for verification testing.

Overview

frost-verify is a simple signing verification tool that can:

• Verify FROST signatures against messages using public key packages
• Generate test signatures and public key packages for testing purposes

The tool supports multiple ciphersuites and is compatible with the public key package format used by other ZF FROST CLI tools.

Installation

You can install it directly in your Cargo bin directory, so it is globally available in your PATH:

cargo install --path .

Alternatively, you can build from source:

cd frost-verify
cargo build --release

The binary will be available at target/release/frost-verify.

Or you can run it directly with:

cargo run -- [OPTIONS] <COMMAND>

Dependencies

This tool uses the following major dependencies:

• frost-core 2.0.0 - Core FROST functionality
• frost-ed25519 2.0.0 - Ed25519 ciphersuite support
• frost-secp256k1-tr 2.1.0 - Secp256k1 Taproot ciphersuite support
• clap 4.5.23 - Command-line argument parsing

Usage

The tool provides two main subcommands:

frost-verify <COMMAND>

Commands:
  verify     Verify a FROST signature
  test-sign  Generate test signature data for verification testing
  help       Print this message or the help of the given subcommand(s)

Verify Command

Verify a FROST signature against a message using either a JSON public key package or a TOML credential file.

frost-verify verify [OPTIONS] --message <MESSAGE> --signature <SIGNATURE> <--public-key-package <FILE> | --credential <FILE>>

Options

• -P, --public-key-package <FILE> - Public key package file (JSON format)
• -C, --credential <FILE> - Credential file (TOML format) containing group information
• -m, --message <FILE> - Message file containing raw bytes to verify against (required)
• -s, --signature <FILE> - Signature file containing the raw signature bytes (required)
• -c, --ciphersuite <SUITE> - Ciphersuite to use (auto-detected from credential file if using --credential)
• -q, --quiet - Quiet mode: no output, just exit codes (0=success, 1=failure)

Note: You must provide either --public-key-package OR --credential, but not both.

Supported Ciphersuites

The tool accepts ciphersuite identifiers in multiple formats:

• Ed25519: ed25519 or FROST-ED25519-SHA512-v1
• Secp256k1-TR: secp256k1-tr or FROST-secp256k1-SHA256-TR-v1
• RedPallas: redpallas or FROST(Pallas, BLAKE2b-512)

When using --credential, the ciphersuite is automatically detected from the credential file and normalized to the appropriate format.

Exit Codes

• 0 - Signature verification passed
• 1 - Signature verification failed or error occurred

Test-Sign Command

Generate test signature data for verification testing. This creates both a signature and a corresponding public key package that can be used to test the verification functionality.

frost-verify test-sign [OPTIONS] --message <MESSAGE> --signature <SIGNATURE>

Options

• -m, --message <FILE> - Message file to be signed (required)
• -s, --signature <FILE> - Output signature file (raw binary) (required)
• -P, --public-key-package <FILE> - Output public key package file (JSON) [default: public-key-package.json]
• -c, --ciphersuite <SUITE> - Ciphersuite to use for signing [default: ed25519]
• -q, --quiet - Quiet mode: no output, just exit codes

File Formats

Message Files

Message files contain the raw bytes to be signed or verified. They can contain any binary data.

Signature Files

Signature files contain the raw 64-byte Schnorr signature output by the signing process. They are binary files rather than text. To inspect their contents you can use tools such as xxd:

$ xxd -p signature.bin
503c4eb5b7b37c2d16374d7b530a63438850360418f97d9c7ed91fde42b0da7bd92af47052feef585e22c87623e13ac3670e0cdb4703d6f703d6720c053d240b

Public Key Package Files

Public key packages can be provided in two formats:

JSON Format

JSON files containing the FROST group public key and verification information. They use the same format as other ZF FROST CLI tools.

Example structure:

{
  "header": {
    "version": 0,
    "ciphersuite": "FROST-ED25519-SHA512-v1"
  },
  "verifying_shares": {
    "0000000000000001": "...",
    "0000000000000002": "..."
  },
  "verifying_key": "..."
}

TOML Credential Format

TOML credential files created by the ZF FROST server/client. These contain the public_key_package as a hex-encoded byte array.

Example structure:

version = 0

[group.group_verifying_key_hex]
description = "My FROST Group"
ciphersuite = "FROST-secp256k1-SHA256-TR-v1"
public_key_package = "00230f8ab30394cf4a8d272bacba3e27cb440000dff48e..."

When using credential files with --credential, the ciphersuite is auto-detected from the file.

Examples

Basic Verification Workflow

1. Create a message file:

   echo "Hello, FROST!" > message.txt

2. Generate test signature data:

   frost-verify test-sign --message message.txt --signature signature.bin

   This creates:

   • signature.bin - binary signature (64 bytes)
   • public-key-package.json - JSON public key package

3. Verify the signature:

   frost-verify verify --message message.txt --signature signature.bin

   Output:

   ✅ Signature verification: PASSED
   

Using Different Ciphersuites

Generate and verify with secp256k1-tr:

# Generate test data with secp256k1-tr
frost-verify test-sign \
  --ciphersuite secp256k1-tr \
  --message message.txt \
  --signature signature-secp.bin \
  --public-key-package pubkey-secp.json

# Verify with secp256k1-tr
frost-verify verify \
  --ciphersuite secp256k1-tr \
  --message message.txt \
  --signature signature-secp.bin \
  --public-key-package pubkey-secp.json

Verifying with Credential Files

If you have a TOML credential file from the ZF FROST server/client, you can verify signatures directly:

# Verify using a credential file (ciphersuite auto-detected)
frost-verify verify \
  --credential alice.toml \
  --message message.txt \
  --signature signature.bin

This is particularly useful for verifying signatures from server-generated DKG shares.

Custom File Paths

Specify custom paths for all files:

frost-verify verify \
  --message /path/to/message.txt \
  --signature /path/to/signature.bin \
  --public-key-package /path/to/pubkey.json

Quiet Mode for Automation

Use quiet mode in scripts where you only need exit codes:

# Generate test data quietly
frost-verify test-sign --quiet \
  --message message.txt \
  --signature signature.bin

# Verify quietly and check exit code
if frost-verify verify --quiet \
     --message message.txt \
     --signature signature.bin; then
  echo "Signature is valid"
else
  echo "Signature is invalid"
fi

Verification Failure Example

Test verification with a tampered message:

# Generate original signature
echo "Original message" > original.txt
frost-verify test-sign --message original.txt --signature sig.bin

# Try to verify with different message
echo "Tampered message" > tampered.txt
frost-verify verify --message tampered.txt --signature sig.bin

Output:

❌ Signature verification: FAILED

Integration with Other FROST Tools

This tool is designed to work with public key packages generated by other ZF FROST CLI tools. If you have a public key package from a real FROST ceremony, you can use it directly:

# Use a public key package from an actual FROST ceremony
frost-verify verify \
  --message your-message.txt \
  --signature frost-generated-signature.bin \
  --public-key-package frost-pubkey-package.json

Error Handling

The tool provides clear error messages for common issues:

• File not found: Error: No such file or directory
• Invalid signature format: Error: Failed to deserialize signature
• Invalid public key package: Error: invalid character '...' at line 1 column 1
• Signature verification failure: ❌ Signature verification: FAILED

All errors result in exit code 1, while successful operations return exit code 0.

Troubleshooting

Common Issues

1. "Failed to deserialize signature"

   • Ensure the signature file contains a complete 64-byte binary signature
   • Check that the signature was generated with the same ciphersuite

2. "Invalid character in JSON"

   • Verify the public key package is valid JSON
   • Ensure the file wasn't corrupted during transfer

3. "Unsupported ciphersuite"

   • Check that the ciphersuite name is exactly ed25519 or secp256k1-tr
   • Ensure you're using the same ciphersuite for both generation and verification

Debug Information

Run with cargo run -- instead of the compiled binary to see additional debug information and compilation warnings.