Minisign tool ⁄ 𝐃𝐈𝐒𝐔☆𝟏𝟗𝟓𝟎

Minisign by Frank Denis

Minisign is a dead simple tool to sign files and verify signatures.

It is portable, lightweight, and uses the highly secure
Ed25519 public-key signature system.

Creating a key pair

$ minisign -G

The public key is printed and put into the minisign.pub file. The secret key
is encrypted and saved as a file named ~/.minisign/minisign.key.

Signing a file

$ minisign -Sm myfile.txt

Or to include a comment in the signature, that will be verified and
displayed when verifying the file:

$ minisign -Sm myfile.txt -t 'This comment will be signed as well'

The signature is put into myfile.txt.minisig.

Starting with version 0.8, multiple files can also be signed at once:

$ minisign -Sm file1.txt file2.txt *.jpg

Verifying a file

$ minisign -Vm myfile.txt -P RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3

$ minisign -Vm myfile.txt -p signature.pub

This requires the signature myfile.txt.minisig to be present in the same
directory.

The public key can either reside in a file (./minisign.pub by default) or be
directly specified on the command line.

Usage


Usage:
minisign -G [-f] [-p pubkey_file] [-s seckey_file] [-W]
minisign -R [-s seckey_file] [-p pubkey_file]
minisign -C [-s seckey_file] [-W]
minisign -S [-l] [-x sig_file] [-s seckey_file] [-c untrusted_comment] [-t trusted_comment] -m file [file ...]
minisign -V [-H] [-x sig_file] [-p pubkey_file | -P pubkey] [-o] [-q] -m file

-G generate a new key pair
-R recreate a public key file from a secret key file
-C change/remove the password of the secret key
-S sign files
-V verify that a signature is valid for a given file
-H require input to be prehashed
-l sign using the legacy format
-m <file> file to sign/verify
-o combined with -V, output the file content after verification
-p <pubkey_file> public key file (default: ./minisign.pub)
-P <pubkey> public key, as a base64 string
-s <seckey_file> secret key file (default: ~/.minisign/minisign.key)
-W do not encrypt/decrypt the secret key with a password
-x <sigfile> signature file (default: <file>.minisig)
-c <comment> add a one-line untrusted comment
-t <comment> add a one-line trusted comment
-q quiet mode, suppress output
-Q pretty quiet mode, only print the trusted comment
-f force. Combined with -G, overwrite a previous key pair
-v display version number

Trusted comments

Signature files include an untrusted comment line that can be freely
modified, even after signature creation.

They also include a second comment line, that cannot be modified
without the secret key.

Trusted comments can be used to add instructions or application-specific
metadata (intended file name, timestamps, resource identifiers,
version numbers to prevent downgrade attacks).

Compilation / installation

Using Zig

Dependencies:

libsodium

Compilation:

$ zig build -Drelease-small

Using Cmake

Dependencies

libsodium
cmake
make
pkg-config
a C compilation toolchain

Compilation:

$ mkdir build
$ cd build
$ cmake ..
$ make
# make install

Pre-hashing

By default, files are signed and verified with very low memory requirements, by pre-hashing the content.

Signatures that are not pre-hashed can be rejected with the -H switch. Support for these legacy signatures will
eventually be removed.

Signature format

untrusted comment: <arbitrary text>
base64(<signature_algorithm> || <key_id> || <signature>)
trusted_comment: <arbitrary text>
base64(<global_signature>)

signature_algorithm: Ed (legacy) or ED (hashed)
key_id: 8 random bytes, matching the public key
signature (legacy): ed25519(<file data>)
signature (prehashed): ed25519(Blake2b-512(<file data>))
global_signature: ed25519(<signature> || <trusted_comment>)

New implementations must use the hashed signature format; support for the legacy one is optional and should not
be done by default.

Public key format

untrusted comment: <arbitrary text>
base64(<signature_algorithm> || <key_id> || <public_key>)

signature_algorithm: Ed
key_id: 8 random bytes
public_key: Ed25519 public key

Secret key format

untrusted comment: <arbitrary text>
base64(<signature_algorithm> || <kdf_algorithm> || <cksum_algorithm> ||
       <kdf_salt> || <kdf_opslimit> || <kdf_memlimit> || <keynum_sk>)

signature_algorithm: Ed
kdf_algorithm: Sc
cksum_algorithm: B2
kdf_salt: 32 random bytes
kdf_opslimit: crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_SENSITIVE
kdf_memlimit: crypto_pwhash_scryptsalsa208sha256_MEMLIMIT_SENSITIVE
keynum_sk:
<kdf_output> ^ (<key_id> || <secret_key> || <public_key> || <checksum>),
104 bytes
key_id: 8 random bytes
secret_key: Ed25519 secret key
public_key: Ed25519 public key
checksum:
Blake2b-256(<signature_algorithm> || <key_id> || <secret_key> || <public_key>),
32 bytes

𝐃𝐈𝐒𝐔☆𝟏𝟗𝟓𝟎

Minisign tool