X-Git-Url: https://pd.if.org/git/?p=zpackage;a=blobdiff_plain;f=doc%2Fzpm-sign.8;h=d89388fa00d4f574a08dce2cda3053af5e23af0f;hp=1682eec374c30d01ff309a7932cd37369174b237;hb=0c2216d1e0dc8565a6bf61c9572e47bb1ae1c1fb;hpb=27f7fa2a8566beb45fc813fcd8ff3f1e7c738883

diff --git a/doc/zpm-sign.8 b/doc/zpm-sign.8
index 1682eec..d89388f 100644
--- a/doc/zpm-sign.8
+++ b/doc/zpm-sign.8
@@ -1,25 +1,25 @@
-.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"
@@ -33,8 +33,7 @@ zpm-sign \- manage package signatures
 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.
@@ -44,6 +43,20 @@ Signatures are always detached signatures.
 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.
@@ -52,6 +65,27 @@ 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
+.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
@@ -118,9 +152,15 @@ 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.
+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,
@@ -149,14 +189,16 @@ 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 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
@@ -169,6 +211,8 @@ public key format is:
 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
@@ -191,11 +235,39 @@ a revocation signature, used to revoke 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
@@ -214,6 +286,8 @@ used for this, but the semantics then need to be designed.
 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