diff --git a/technology/cryptography/minisign.md b/technology/cryptography/minisign.md new file mode 100644 index 0000000..9d3ff90 --- /dev/null +++ b/technology/cryptography/minisign.md @@ -0,0 +1,139 @@ +--- +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 to sign/verify | +| `-o` | Combined with `-V`, output the file content after verification | +| `-p ` | Public key file (default: `./minisign.pub`) | +| `-P `| Public key, as a base64 string | +| `-s ` | Secret key file (default: `~/.minisign/minisign.key`) | +| `-W` | Do not encrypt/decrypt the secret key with a password | +| `-x `| Signature file (default: `.minisig`) | +| `-c `| Add a one-line untrusted comment | +| `-t `| 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: +base64( || || ) +trusted_comment: +base64() +``` + +- `signature_algorithm`: `Ed` (legacy) or `ED` (hashed) +- `key_id`: 8 random bytes, matching the public key +- `signature` (legacy): `ed25519()` +- `signature` (prehashed): `ed25519(Blake2b-512())` +- `global_signature`: `ed25519( || )` + +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: +base64( || || ) +``` + +- `signature_algorithm`: `Ed` +- `key_id`: 8 random bytes +- `public_key`: Ed25519 public key + + +## Secret key format +``` +untrusted comment: +base64( || || || + || || || ) +``` + +- `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`: ` ^ ( || || || )`, 104 bytes +- `key_id`: 8 random bytes +- `secret_key`: Ed25519 secret key +- `public_key`: Ed25519 public key +- `checksum`: `Blake2b-256( || || || )`, 32 bytes