From: Nathan Wagner Date: Sat, 2 Mar 2019 02:01:29 +0000 (+0000) Subject: expand sign docs X-Git-Url: https://pd.if.org/git/?p=zpackage;a=commitdiff_plain;h=62ebf390fa9ec8f7de054648e978919386fddf2f expand sign docs --- diff --git a/Makefile b/Makefile index 053ab9b..d2acd75 100644 --- a/Makefile +++ b/Makefile @@ -182,7 +182,7 @@ zpm-add: src/add.o libzpm.a libelf.a zpm-quote: src/quote.o $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $< -db.sql: schema/main.sql schema/syncconflicts.sql schema/syncinfo.sql schema/preserve_packages.sql schema/age.sql +db.sql: schema/main.sql schema/syncconflicts.sql schema/syncinfo.sql schema/preserve_packages.sql schema/age.sql schema/sign.sql echo 'begin;' > $@ cat $+ >> $@ echo 'commit;' >> $@ diff --git a/doc/zpm-sign.8 b/doc/zpm-sign.8 index 7ee2936..1682eec 100644 --- a/doc/zpm-sign.8 +++ b/doc/zpm-sign.8 @@ -1,4 +1,4 @@ -.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 @@ -38,8 +38,29 @@ representions of the signature metadata and the actual signature value. .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 @@ -65,39 +86,142 @@ Output the raw signature, rather than a full zpm certificate. 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 diff --git a/zpm-merge b/zpm-merge index 840296f..48d826f 100755 --- a/zpm-merge +++ b/zpm-merge @@ -213,6 +213,7 @@ merge_list() { printf "insert or ignore into elfneeded select * from remote.elfneeded;\n" printf "insert or ignore into elflibraries select * from remote.elflibraries;\n" + printf "insert or ignore into package_signatures select * from remote.package_signatures PS where PS.packagehash in (select hash from remote.packages);\n" printf "commit;\n" ) | zpm shell $target