-.TH zpm-sign 8 2019-03-02 "ZPM 0.6.2"
+.TH zpm-sign 8 2019-03-09 "ZPM 0.7.0"
.SH NAME
zpm-sign \- manage package signatures
.SH SYNOPSIS
.B zpm sign
[
-.B -hrdsgev
+.B \-vsge
]
[
-.BI -f " sigfile"
+.B \-Hhrd
]
[
.BI -o " outfile"
]
[
-.BI -S " sigstring"
+.BI -i " input"
]
[
-.BI -k " keystring"
+.BI -k " keyid"
]
[
-.BI -K " keyfile"
+.BI -I " inputhexstring"
]
[
.BI -p " passphrase"
manages signatures on zpm packages. It can generate signing keys,
sign files, and verify signatures. The ed25519 algorithms are
used exclusively, and all the signature code is taken from the
-ref10 implementation. Signatures themselves are hex encoded
-representions of the signature metadata and the actual signature value.
+ref10 implementation.
.PP
Private keys are potentially encrypted with chacha20 before storing
them on disk.
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).
+The \-i option can be used to specify a
+key file to look for a key in. If the \-k option is given, or the ZPM_KEY
+environment variable is set, a key which matches that string in the id portion
+of the key is looked for, otherwise the first secret key found is used. If the
+\-i option is not given, a key will be searched for in a file given with the
+ZPM_KEYFILE environment variable or in ~/.zpm/key Alternatively, a hex encoded
+private key can be specified directly with the \-I option. If several of these
+options apply, The \-I option takes precedence. I.e. command line beats
+environment variables beats defaults.
+.PP
+If the private key needs a passphrase, it can be specified via the \-p
+option or the ZPM_KEYPASS environment variable, neither of which
+is secure. Otherwise, if /dev/tty can be opened, zpm-sign will
+attempt to ask for a passphrase.
.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.
key is contained in the signature.
.SS Signing Mode
To sign data, use \-s
+.PP
+Inputs to a regular signature are:
+.TP the secret key used to sign the message,
+See above for methods to specify a secret key.
+.TP
+Signature timestamp
+Defaults to the current time read from the system clock.
+Can be specified with the \-T option.
+.TP
+Expiration timestamp
+Defaults to never. Can be specified with the \-E optino.
+.TP
+The message to be signed.
+Is read from stdin, a command line argument, or the \-m option.
+If both an argument and a \-m option are given the \-m option wins.
+.PP
+When a raw signature is created (with the \-r option), the
+.PP
+The signature is output to stdout, or the output file given with the
+\-o option. A signature packet is output unless the \-b option is given,
+in which case only the hex encoded signature is output.
.SS Key Generation Mode
A new private key is generated with \-g
.SS Verification Mode
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.
+Signatures and keys are output as hexencoded packet bytestrings. All are 256
+bytes, (512 bytes as hex encoded). Reserved bytes in packet formats must be
+zero. The last 8 bytes are reserved.
+.PP
+On disk format is a series of 32 bytes, hex encoded, followed by
+a newline. This takes one line per 32 bytes, thus 4 lines for 128,
+8 lines for 256. If we waste 8 bytes at the end, we have 8 lines
+and 512 bytes encoded, the last line will be short by 16 characters,
+so that the actual size on disk is 512 bytes.
.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,
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 creation time, little endian
+8 bytes expiration time, little endian
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.
+120 bytes id
+8 bytes reserved trailer
.EE
.SS Public Keys
.EX
0x.. 32 bytes public key
0x.. 24 bytes reserved : create, expire, 8 reserved
0x.. 64 bytes reserved : self sig
+ 120 bytes reserved : id = 1 byte id length, n bytes id, zeros
+ 8 bytes reserved trailer
0x.. revocation signatures
0x.. user id packets
0x.. certification signatures
0x.. 64 bytes of actual signature
0x.. 32 bytes of public key making the signature
0x.. 8 bytes reserved
+ 120 bytes reserved
+ 8 bytes reserved trailer
.EE
.SH EXAMPLES
.TP
-.B zpm sign
-lists all files in the local database
+.B zpm sign -s \fIpath\fR
+Sign the contents of the file found at \fIpath\fR using the default secret key
+with a signing timestamp of the current time and no expiration date. The
+signature packet will be written to stdout.
+.TP
+.B zpm sign -s -m 'foo'
+Sign the string 'foo'.
+.TP
+.B printf '%s' foo | zpm sign -s
+Sign the string 'foo' as in the above example, the message being read
+from stdin.
+.TP
+.B zpm sign -s -r -m 'foo'
+Sign the string 'foo' directly using the default private key, no
+additional information is signed, and the output is a hex encoded
+raw signature with no additional newlines, making up 128 characters
+of output. There is no way to output just the raw signature while
+still adding the timestamps and such, but the raw signature can be
+extracted from a signature packet.
+.TP
+.B zpm sign -s -r \\
+-I 'c5aa8df43f9f837bedb7442f31dcb7b166d38535076f094b85ce3a2e0b4458f7' \\
+-h -m 'af82'
+Sign the two byte hex encoded message af82 with the raw hex encoded
+secret key given by the -I argument. The result will be
+6291d657deec24024827e69c3abe01a30ce548a284743a445e3680d7db5ac3ac
+18ff9b538d16f290ae67f760984dc6594a7c15e9716ed28dc027beceea1ec40a
+all on a single line with no trailing newline.
.SH EXIT STATUS
0 on success non zero on failure
.SH BUGS
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.
+.PP
+Chacha20 is used to encrypt private keys.
.SH FILES
~/.zpm/keys
/var/lib/zpm/keys
projects / zpackage / blobdiff