mirror of
https://github.com/jedisct1/minisign.git
synced 2025-04-04 19:37:48 +03:00
Added manual page
I thought it would be nice to have a man page for this wonderful piece of software, especially with it being available in various package managers like Homebrew. This man page is basically a reformatting (and slight reorganizing to fit the typical man page structure) of the official docs. src/manpage.md is the Markdown source which can generate the actual man page (share/man/man1/minisign.1) using ronn <http://rtomayko.github.com/ronn/> Update: Corrected a few typos that I didn't catch before original submission.
This commit is contained in:
Corey Edwards
parent
e748f644dd
commit
7f41769d67
2 changed files with 356 additions and 0 deletions
196
share/man/man1/minisign.1
Normal file
196
share/man/man1/minisign.1
Normal file
|
|
@ -0,0 +1,196 @@
|
|||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "MINISIGN" "1" "December 2015" "" ""
|
||||
.
|
||||
.SH "NAME"
|
||||
\fBminisign\fR \- A dead simple tool to sign files and verify signatures\.
|
||||
.
|
||||
.SH "SYNOPSIS"
|
||||
\fBminisign\fR \-G [\-p pubkey] [\-s seckey] \fBminisign\fR \-S [\-H] [\-x sigfile] [\-s seckey] [\-c untrusted_comment] [\-t trusted_comment] \-m <file> \fBminisign\fR \-V [\-x sigfile] [\-p pubkeyfile | \-P pubkey] [\-o] [\-q] \-m file
|
||||
.
|
||||
.SH "DESCRIPTION"
|
||||
\fBMinisign\fR is a dead simple tool to sign files and verify signatures\.
|
||||
.
|
||||
.P
|
||||
It is portable, lightweight, and uses the highly secure Ed25519 \fIhttp://ed25519\.cr\.yp\.to/\fR public\-key signature system\.
|
||||
.
|
||||
.SH "OPTIONS"
|
||||
These options control the actions of \fBminisign\fR\.
|
||||
.
|
||||
.TP
|
||||
\fB\-G\fR
|
||||
Generate a new key pair
|
||||
.
|
||||
.TP
|
||||
\fB\-S\fR
|
||||
Sign a file
|
||||
.
|
||||
.TP
|
||||
\fB\-V\fR
|
||||
Verify that a signature is valid for a given file
|
||||
.
|
||||
.TP
|
||||
\fB\-m <file>\fR
|
||||
File to sign/verify
|
||||
.
|
||||
.TP
|
||||
\fB\-o\fR
|
||||
Combined with \-V, output the file content after verification
|
||||
.
|
||||
.TP
|
||||
\fB\-H\fR
|
||||
Combined with \-S, pre\-hash in order to sign large files
|
||||
.
|
||||
.TP
|
||||
\fB\-p <pubkeyfile>\fR
|
||||
Public key file (default: \./minisign\.pub)
|
||||
.
|
||||
.TP
|
||||
\fB\-P <pubkey>\fR
|
||||
Public key, as a base64 string
|
||||
.
|
||||
.TP
|
||||
\fB\-s <seckey>\fR
|
||||
Secret key file (default: \./minisign\.key)
|
||||
.
|
||||
.TP
|
||||
\fB\-x <sigfile>\fR
|
||||
Signature file (default: <file>\.minisig)
|
||||
.
|
||||
.TP
|
||||
\fB\-c <comment>\fR
|
||||
Add a one\-line untrusted comment
|
||||
.
|
||||
.TP
|
||||
\fB\-t <comment>\fR
|
||||
Add a one\-line trusted comment
|
||||
.
|
||||
.TP
|
||||
\fB\-q\fR
|
||||
Quiet mode, suppress output
|
||||
.
|
||||
.TP
|
||||
\fB\-Q\fR
|
||||
Pretty quiet mode, only print the trusted comment
|
||||
.
|
||||
.TP
|
||||
\fB\-v\fR
|
||||
Display version number
|
||||
.
|
||||
.SH "EXAMPLES"
|
||||
Creating a key pair
|
||||
.
|
||||
.P
|
||||
\fBminisign\fR \-G
|
||||
.
|
||||
.P
|
||||
The public key is printed and put into the \fBminisign\.pub\fR file\. The secret key is encrypted and saved as a file named \fBminisign\.key\fR\.
|
||||
.
|
||||
.P
|
||||
Signing a file
|
||||
.
|
||||
.P
|
||||
$ \fBminisign\fR \-Sm myfile\.txt
|
||||
.
|
||||
.P
|
||||
Or to include a comment in the signature, that will be verified and displayed when verifying the file:
|
||||
.
|
||||
.P
|
||||
$ \fBminisign\fR \-Sm myfile\.txt \-t \'This comment will be signed as well\'
|
||||
.
|
||||
.P
|
||||
Verifying a file
|
||||
.
|
||||
.P
|
||||
$ \fBminisign\fR \-Vm myfile\.txt \-p <pubkey>
|
||||
.
|
||||
.P
|
||||
or
|
||||
.
|
||||
.P
|
||||
$ \fBminisign\fR \-Vm myfile\.txt \-p signature\.pub
|
||||
.
|
||||
.P
|
||||
This requires the signature \fBmyfile\.txt\.minisig\fR to be present in the same directory\.
|
||||
.
|
||||
.P
|
||||
The public key can either reside in a file (\fB\./minisign\.pub\fR by default) or be directly specified on the command line\.
|
||||
.
|
||||
.SH "Notes"
|
||||
\fBTrusted comments\fR
|
||||
.
|
||||
.P
|
||||
Signature files include an untrusted comment line that can be freely modified, even after signature creation\.
|
||||
.
|
||||
.P
|
||||
They also include a second comment line, that cannot be modified without the secret key\.
|
||||
.
|
||||
.P
|
||||
Trusted comments can be used to add instructions or application\-specific metadata (intended file name, timestamps, resource identifiers, version numbers to prevent downgrade attacks)\.
|
||||
.
|
||||
.P
|
||||
\fBCompatibility with OpenBSD signify\fR
|
||||
.
|
||||
.P
|
||||
Signatures written by \fBminisign\fR can be verified using OpenBSD\'s \fBsignify\fR tool: public key files and signature files are compatible\.
|
||||
.
|
||||
.P
|
||||
However, \fBminisign\fR uses a slightly different format to store secret keys\.
|
||||
.
|
||||
.P
|
||||
\fBMinisign\fR signatures include trusted comments in addition to untrusted comments\. Trusted comments are signed, thus verified, before being displayed\.
|
||||
.
|
||||
.P
|
||||
This adds two lines to the signature files, that signify silently ignores\.
|
||||
.
|
||||
.P
|
||||
\fBPre\-hashing\fR
|
||||
.
|
||||
.P
|
||||
By default, signing and verification require as much memory as the size of the file\.
|
||||
.
|
||||
.P
|
||||
Since \fBMinisign 0\.6\fR, huge files can be signed and verified with very low memory requirements, by pre\-hashing the content\.
|
||||
.
|
||||
.P
|
||||
The \-H command\-line switch, in combination with \-S, generates a pre\-hashed signature (HashEdDSA):
|
||||
.
|
||||
.P
|
||||
$ \fBminisign\fR \-SHm myfile\.txt
|
||||
.
|
||||
.P
|
||||
Verification of such a signature doesn\'t require any specific switch: the appropriate algorithm will automatically be detected\.
|
||||
.
|
||||
.P
|
||||
Signatures generated that way are not compatible with OpenBSD\'s \fBsignify\fR tool and are not compatible with \fBMinisign\fR versions prior to 0\.6
|
||||
.
|
||||
.P
|
||||
\fBSignature format\fR
|
||||
.
|
||||
.P
|
||||
untrusted comment: <arbitrary text> base64(<signature_algorithm> || <key_id> || <signature>) trusted_comment: <arbitrary text> base64(<global_signature>)
|
||||
.
|
||||
.P
|
||||
signature_algorithm: Ed key_id: 8 random bytes, matching the public key signature (PureEdDSA): ed25519(<file data>) signature (HashedEdDSA): ed25519(Blake2b\-512(<file data>)) global_signature: ed25519(<signature> || <trusted_comment>)
|
||||
.
|
||||
.P
|
||||
\fBPublic key format\fR
|
||||
.
|
||||
.P
|
||||
untrusted comment: <arbitrary text> base64(<signature_algorithm> || <key_id> || <public_key>)
|
||||
.
|
||||
.P
|
||||
signature_algorithm: Ed key_id: 8 random bytes public_key: Ed25519 public key
|
||||
.
|
||||
.P
|
||||
\fBSecret key format\fR
|
||||
.
|
||||
.P
|
||||
untrusted comment: <arbitrary text> base64(<signature_algorithm> || <kdf_algorithm> || <cksum_algorithm> || <kdf_salt> || <kdf_opslimit> || <kdf_memlimit> || <keynum_sk>)
|
||||
.
|
||||
.P
|
||||
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>), 32 bytes
|
||||
.
|
||||
.SH "AUTHOR"
|
||||
Frank Denis (github@pureftpd\.org) \fIhttps://00f\.net/\fR
|
||||
160
src/manpage.md
Normal file
160
src/manpage.md
Normal file
|
|
@ -0,0 +1,160 @@
|
|||
<!---
|
||||
This man page can be generated using ronn - http://rtomayko.github.com/ronn/
|
||||
-->
|
||||
minisign(1) -- A dead simple tool to sign files and verify signatures.
|
||||
=============================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
`minisign` -G [-p pubkey] [-s seckey]
|
||||
`minisign` -S [-H] [-x sigfile] [-s seckey] [-c untrusted_comment] [-t trusted_comment] -m <file>
|
||||
`minisign` -V [-x sigfile] [-p pubkeyfile | -P pubkey] [-o] [-q] -m file
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
**Minisign** is a dead simple tool to sign files and verify signatures.
|
||||
|
||||
It is portable, lightweight, and uses the highly secure [Ed25519](http://ed25519.cr.yp.to/) public-key signature system.
|
||||
|
||||
## OPTIONS
|
||||
|
||||
These options control the actions of `minisign`.
|
||||
|
||||
* `-G`:
|
||||
Generate a new key pair
|
||||
* `-S`:
|
||||
Sign a file
|
||||
* `-V`:
|
||||
Verify that a signature is valid for a given file
|
||||
* `-m <file>`:
|
||||
File to sign/verify
|
||||
* `-o`:
|
||||
Combined with -V, output the file content after verification
|
||||
* `-H`:
|
||||
Combined with -S, pre-hash in order to sign large files
|
||||
* `-p <pubkeyfile>`:
|
||||
Public key file (default: ./minisign.pub)
|
||||
* `-P <pubkey>`:
|
||||
Public key, as a base64 string
|
||||
* `-s <seckey>`:
|
||||
Secret key file (default: ./minisign.key)
|
||||
* `-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
|
||||
* `-v`:
|
||||
Display version number
|
||||
|
||||
|
||||
## EXAMPLES
|
||||
|
||||
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.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'
|
||||
|
||||
Verifying a file
|
||||
|
||||
$ `minisign` -Vm myfile.txt -p <pubkey>
|
||||
|
||||
or
|
||||
|
||||
$ `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.
|
||||
|
||||
## Notes
|
||||
|
||||
**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).
|
||||
|
||||
**Compatibility with OpenBSD signify**
|
||||
|
||||
Signatures written by `minisign` can be verified using OpenBSD's `signify` tool: public key files and signature files are compatible.
|
||||
|
||||
However, `minisign` uses a slightly different format to store secret keys.
|
||||
|
||||
`Minisign` signatures include trusted comments in addition to untrusted comments. Trusted comments are signed, thus verified, before being displayed.
|
||||
|
||||
This adds two lines to the signature files, that signify silently ignores.
|
||||
|
||||
**Pre-hashing**
|
||||
|
||||
By default, signing and verification require as much memory as the size of the file.
|
||||
|
||||
Since `Minisign 0.6`, huge files can be signed and verified with very low memory requirements, by pre-hashing the content.
|
||||
|
||||
The -H command-line switch, in combination with -S, generates a pre-hashed signature (HashEdDSA):
|
||||
|
||||
$ `minisign` -SHm myfile.txt
|
||||
|
||||
Verification of such a signature doesn't require any specific switch: the appropriate algorithm will automatically be detected.
|
||||
|
||||
Signatures generated that way are not compatible with OpenBSD's `signify` tool and are not compatible with `Minisign` versions prior to 0.6
|
||||
|
||||
**Signature format**
|
||||
|
||||
untrusted comment: <arbitrary text>
|
||||
base64(<signature_algorithm> || <key_id> || <signature>)
|
||||
trusted_comment: <arbitrary text>
|
||||
base64(<global_signature>)
|
||||
|
||||
signature_algorithm: Ed
|
||||
key_id: 8 random bytes, matching the public key
|
||||
signature (PureEdDSA): ed25519(<file data>)
|
||||
signature (HashedEdDSA): ed25519(Blake2b-512(<file data>))
|
||||
global_signature: ed25519(<signature> || <trusted_comment>)
|
||||
|
||||
**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>), 32 bytes
|
||||
|
||||
|
||||
## AUTHOR
|
||||
|
||||
Frank Denis (github@pureftpd.org) <https://00f.net/>
|
||||
Loading…
Add table
Add a link
Reference in a new issue