-.TH zpm-sign 8 2019-02-15 "ZPM 0.3"
+.TH zpm-sign 8 2019-03-02 "ZPM 0.6.2"
.SH NAME
zpm-sign \- manage package signatures
.SH SYNOPSIS
.PP
Private keys are potentially encrypted with chacha20 before storing
them on disk.
+.PP
+Signatures are always detached signatures.
+.SS Specifying a key
+The \-k option is used to specify a key. Keys are looked for
+in the keyring file (or taken literally from the command line
+if the \-h option is given).
+.PP
+For signing or generating a public key, a private key is looked for, and if not
+specified, the first one found in the keyring file is used.
+.PP
+For signature verification, no key needs to be specified as the public
+key is contained in the signature.
+.SS Signing Mode
+To sign data, use \-s
+.SS Key Generation Mode
+A new private key is generated with \-g
+.SS Verification Mode
+A signature can be verified with \-v
.SH OPTIONS
+.TP
.B -r
+Output the raw signature or key data without wrapping it in a
+packet structure.
.TP
.B \-g
Generate a private key
This also just signs the data given, without any signature
metadata.
.TP
-.BI \-p passphrase
-Specify a passphrase to decrypt a private key.
+.BI \-p " passphrase"
+Specify a passphrase to decrypt or encrypt a private key. If not given here,
+the environment variable ZPM_SIGN_PP is used. Neither of these options
+are very secure, the command line in particular is generally readable
+by other processes.
.TP
-.BI \-m message
+.BI \-m " message"
Specify a message to be signed or verified. If not set with the -m option, the
message is taken from file named with the first non-option argument.
.TP
-.BI \-k path
+.BI \-k " path"
Take the private key for message signing from the path given. This
defaults to ~/.zpm/key. If ~/.zpm/key is not found and the euid
is root, /var/lib/zpm/key is tried.
.TP
-.BI \-K key
+.BI \-K " key"
Take the private key from the command line argument. This is not
particularly secure and is primarily intended for testing.
.TP
-.BI \-S sigstring
+.BI \-S " sigstring"
Use sigstring as the signature to verify.
.TP
-.BI \-m message
+.BI \-m " message"
Specify a message to be signed or verified. If not set with the -m option, the
message is taken from file named with the first non-option argument.
+.TP
+.BI \-t " timestamp"
+Specify a timestamp to be used for signing instead of the current time.
+Must be specified as a decimal representation of the unix timestamp
+to be used.
+.SH PACKET AND FILE FORMAT
+.PP
+Signatures and keys are output as hexencoded packet bytestrings. All are 128
+bytes, (256 bytes as hex encoded). Reserved bytes in packet formats must be
+zero.
+.PP
+Timestamps are 8 byte little endian integers of seconds since the epoch. or
+unix time, or some such. Times are a mess. Unix time is leap second unaware,
+and ambiguous during leap seconds. UTC requires a database of leap seconds for
+past time, and the specified second in the future possibly changes. TAI is
+good, but currently 37 seconds behind UTC, which is just weird.
+.PP
+All key and signature data begin with an 8 byte header, consisting of
+the following:
+.EX
+5A 50 4D 53 = "ZPMS" in ascii.
+01 = one byte version number
+xx = one byte packet type
+xx xx = two bytes packet information
+.EE
+.PP
+There are the following packet types.
+.SS Private Keys
+The public key is derivable from the secret key, so the public key is not
+explicitly stored.
+.EX
+private key format is:
+"ZPMS" 4 byte magic "ZPMS"
+byte 0x01 = version 1
+byte 0x01 = private key
+byte 0x01 = chacha encrypted, 0x00 = plain/raw key bytes
+byte 0x00 reserved, probably "key usage"
+32 bytes private key
+8 bytes creation time
+8 bytes expiration time
+8 bytes password salt, note, nist wants 16, but we're not using nist
+approved hash algorithms anyway.
+64 bytes reserved
+could have 16 bytes of IV for chacha to encrypt.
+Can probably use those, hashed with the password as the salt, but
+not very much salt then.
+.EE
+.SS Public Keys
+.EX
+public key format is:
+"ZPMS" 4 byte magic "ZPMS"
+0x01 1 byte version
+0x02 1 byte "public key packet"
+0x00 1 byte reserved
+0x00 1 byte reserved
+0x.. 32 bytes public key
+0x.. 24 bytes reserved : create, expire, 8 reserved
+0x.. 64 bytes reserved : self sig
+0x.. revocation signatures
+0x.. user id packets
+0x.. certification signatures
+0x.. sub key packets
+.EE
+.SS Signatures
+Data, Key, and Revocation signatures all have the same format,
+with the exception of the packet type byte at offset 5. Type
+0x03 is a data signature used for signing arbitrary data. Type
+0x04 is a key signature used to sign public keys. Type 0x05 is
+a revocation signature, used to revoke signatures.
+.EX
+"ZPMS" 4 byte magic "ZPMS"
+0x01 1 byte version
+0x03 1 byte "signature packet"
+0x00 1 byte reserved
+0x00 1 byte reserved
+0x.. 8 bytes timestamp of signature time
+0x.. 8 bytes timestamp of signature expiration, 0 if none
+0x.. 64 bytes of actual signature
+0x.. 32 bytes of public key making the signature
+0x.. 8 bytes reserved
+.EE
.SH EXAMPLES
.TP
.B zpm sign
lists all files in the local database
.SH EXIT STATUS
0 on success non zero on failure
+.SH BUGS
+.PP
+Timestamps are a mess. Unix time is leap second unaware, and ambiguous during
+leap seconds. UTC requires a database of leap seconds for past time, and the
+specified second in the future possibly changes. TAI is good, but currently 37
+seconds behind UTC, which is just weird. Regardless of the above, unix
+time was chosen for general compatibility with time functions.
+.PP
+There is no binding of a notion of an identity to a public key.
+.PP
+There is no trust level of a public key. A reserved byte could be
+used for this, but the semantics then need to be designed.
+.SH NOTES ON CRYPTOGRAPHY
+The general methods described by SEC 1 Ver 2.0 were followed, but
+this is not an implementation of that scheme, because different
+algorithms are used.
.SH FILES
-/var/lib/zpm/local.db
+~/.zpm/keys
+/var/lib/zpm/keys
.SH ENVIRONMENT
-ZPMDB
+ZPM_KEYRING
.SH AUTHOR
Nathan Wagner
.SH SEE ALSO
.BR zpm (8)
+.R RFC
+.R http://www.secg.org SEC 1 Ver 2.0