---
obj: application
website: https://jedisct1.github.io/minisign
repo: https://github.com/jedisct1/minisign
---

# minisign
Minisign is a dead simple tool to sign files and verify signatures. There is also an [implementation in Rust](https://github.com/jedisct1/rsign2).
It is portable, lightweight, and uses the highly secure Ed25519 public-key signature system.

## Creating a key pair
```shell
$ 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
```shell
$ minisign -Sm myfile.txt
```

Or to include a comment in the signature, that will be verified and displayed when verifying the file:
```shell
$ minisign -Sm myfile.txt -t 'This comment will be signed as well'
```

The signature is put into `myfile.txt.minisig`.

Multiple files can also be signed at once:
```shell
$ minisign -Sm file1.txt file2.txt *.jpg
```

## Verifying a file
```shell
$ minisign -Vm myfile.txt -P RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3
```

or

```shell
$ 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
```

| Option       | Description                                                           |
|--------------|-----------------------------------------------------------------------|
| `-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 the signature is created.

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 such as the intended file name, timestamps, resource identifiers, or version numbers to prevent downgrade attacks.

OpenBSD's signify is conceptually similar to Minisign.

Minisign creates signatures that can be verified by signify; however, signatures created by signify cannot be verified with Minisign because Minisign expects a trusted comment section to be present.
Trusted comments are crucial for describing what has been signed, in addition to merely confirming that a signature exists.

## 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
