pd.if.org Git - zpackage/blob - doc/zpm-sign.8

   1 .TH zpm-sign 8 2019-03-02 "ZPM 0.6.2"
   2 .SH NAME
   3 zpm-sign \- manage package signatures
   4 .SH SYNOPSIS
   5 .B zpm sign
   6 [
   7 .B -hrdsgev
   8 ]
   9 [
  10 .BI -f " sigfile"
  11 ]
  12 [
  13 .BI -o " outfile"
  14 ]
  15 [
  16 .BI -S " sigstring"
  17 ]
  18 [
  19 .BI -k " keystring"
  20 ]
  21 [
  22 .BI -K " keyfile"
  23 ]
  24 [
  25 .BI -p " passphrase"
  26 ]
  27 [
  28 .BI -m " messagestring"
  29 ]
  30 .RI [ file ]
  31 .SH DESCRIPTION
  32 \fBzpm-sign\fR
  33 manages signatures on zpm packages.  It can generate signing keys,
  34 sign files, and verify signatures.  The ed25519 algorithms are
  35 used exclusively, and all the signature code is taken from the
  36 ref10 implementation.  Signatures themselves are hex encoded
  37 representions of the signature metadata and the actual signature value.
  38 .PP
  39 Private keys are potentially encrypted with chacha20 before storing
  40 them on disk.
  41 .PP
  42 Signatures are always detached signatures.
  43 .SS Specifying a key
  44 The \-k option is used to specify a key.  Keys are looked for
  45 in the keyring file (or taken literally from the command line
  46 if the \-h option is given).
  47 .PP
  48 For signing or generating a public key, a private key is looked for, and if not
  49 specified, the first one found in the keyring file is used.
  50 .PP
  51 For signature verification, no key needs to be specified as the public
  52 key is contained in the signature.
  53 .SS Signing Mode
  54 To sign data, use \-s
  55 .SS Key Generation Mode
  56 A new private key is generated with \-g
  57 .SS Verification Mode
  58 A signature can be verified with \-v
  59 .SH OPTIONS
  60 .TP
  61 .B -r
  62 Output the raw signature or key data without wrapping it in a
  63 packet structure.
  64 .TP
  65 .B \-g
  66 Generate a private key
  67 .TP
  68 .B \-e
  69 Extract a public key from a private key.
  70 .TP
  71 .B \-s
  72 Sign a file or message.  In addition to the message to be signed,
  73 signature metadata is signed.
  74 .TP
  75 .B \-v
  76 Verify a signature on a file or message.
  77 .TP
  78 .B \-h
  79 hexencode values
  80 .TP
  81 .B \-d
  82 Increase the debug level.  May be given more than once.
  83 .TP
  84 .B \-r
  85 Output the raw signature, rather than a full zpm certificate.
  86 This also just signs the data given, without any signature
  87 metadata.
  88 .TP
  89 .BI \-p " passphrase"
  90 Specify a passphrase to decrypt or encrypt a private key.  If not given here,
  91 the environment variable ZPM_SIGN_PP is used.  Neither of these options
  92 are very secure, the command line in particular is generally readable
  93 by other processes.
  94 .TP
  95 .BI \-m " message"
  96 Specify a message to be signed or verified.  If not set with the -m option, the
  97 message is taken from file named with the first non-option argument.
  98 .TP
  99 .BI \-k " path"
 100 Take the private key for message signing from the path given.  This
 101 defaults to ~/.zpm/key.  If ~/.zpm/key is not found and the euid
 102 is root, /var/lib/zpm/key is tried.
 103 .TP
 104 .BI \-K " key"
 105 Take the private key from the command line argument.  This is not
 106 particularly secure and is primarily intended for testing.
 107 .TP
 108 .BI \-S " sigstring"
 109 Use sigstring as the signature to verify.
 110 .TP
 111 .BI \-m " message"
 112 Specify a message to be signed or verified.  If not set with the -m option, the
 113 message is taken from file named with the first non-option argument.
 114 .TP
 115 .BI \-t " timestamp"
 116 Specify a timestamp to be used for signing instead of the current time.
 117 Must be specified as a decimal representation of the unix timestamp
 118 to be used.
 119 .SH PACKET AND FILE FORMAT
 120 .PP
 121 Signatures and keys are output as hexencoded packet bytestrings.  All are 128
 122 bytes, (256 bytes as hex encoded).  Reserved bytes in packet formats must be
 123 zero.
 124 .PP
 125 Timestamps are 8 byte little endian integers of seconds since the epoch.  or
 126 unix time, or some such.  Times are a mess.  Unix time is leap second unaware,
 127 and ambiguous during leap seconds.  UTC requires a database of leap seconds for
 128 past time, and the specified second in the future possibly changes.  TAI is
 129 good, but currently 37 seconds behind UTC, which is just weird.
 130 .PP
 131 All key and signature data begin with an 8 byte header, consisting of
 132 the following:
 133 .EX
 134 5A 50 4D 53 = "ZPMS" in ascii.
 135 01          = one byte version number
 136 xx          = one byte packet type
 137 xx xx       = two bytes packet information
 138 .EE
 139 .PP
 140 There are the following packet types.
 141 .SS Private Keys
 142 The public key is derivable from the secret key, so the public key is not
 143 explicitly stored.
 144 .EX
 145 private key format is:
 146 "ZPMS" 4 byte magic "ZPMS"
 147 byte 0x01 = version 1
 148 byte 0x01 = private key
 149 byte 0x01 = chacha encrypted, 0x00 = plain/raw key bytes
 150 byte 0x00 reserved, probably "key usage"
 151 32 bytes private key
 152 8 bytes creation time
 153 8 bytes expiration time
 154 8 bytes password salt, note, nist wants 16, but we're not using nist
 155 approved hash algorithms anyway.
 156 64 bytes reserved
 157 could have 16 bytes of IV for chacha to encrypt.
 158 Can probably use those, hashed with the password as the salt, but
 159 not very much salt then.
 160 .EE
 161 .SS Public Keys
 162 .EX
 163 public key format is:
 164 "ZPMS" 4 byte magic "ZPMS"
 165 0x01   1 byte version
 166 0x02   1 byte "public key packet"
 167 0x00   1 byte reserved
 168 0x00   1 byte reserved
 169 0x..  32 bytes public key
 170 0x..  24 bytes reserved : create, expire, 8 reserved
 171 0x..  64 bytes reserved : self sig
 172 0x..     revocation signatures
 173 0x..     user id packets
 174 0x..     certification signatures
 175 0x..     sub key packets
 176 .EE
 177 .SS Signatures
 178 Data, Key, and Revocation signatures all have the same format,
 179 with the exception of the packet type byte at offset 5.  Type
 180 0x03 is a data signature used for signing arbitrary data.  Type
 181 0x04 is a key signature used to sign public keys.  Type 0x05 is
 182 a revocation signature, used to revoke signatures.
 183 .EX
 184 "ZPMS" 4 byte magic "ZPMS"
 185 0x01   1 byte version
 186 0x03   1 byte "signature packet"
 187 0x00   1 byte reserved
 188 0x00   1 byte reserved
 189 0x..   8 bytes timestamp of signature time
 190 0x..   8 bytes timestamp of signature expiration, 0 if none
 191 0x..  64 bytes of actual signature
 192 0x..  32 bytes of public key making the signature
 193 0x..   8 bytes reserved
 194 .EE
 195 .SH EXAMPLES
 196 .TP
 197 .B zpm sign
 198 lists all files in the local database
 199 .SH EXIT STATUS
 200 0 on success non zero on failure
 201 .SH BUGS
 202 .PP
 203 Timestamps are a mess.  Unix time is leap second unaware, and ambiguous during
 204 leap seconds.  UTC requires a database of leap seconds for past time, and the
 205 specified second in the future possibly changes.  TAI is good, but currently 37
 206 seconds behind UTC, which is just weird.  Regardless of the above, unix
 207 time was chosen for general compatibility with time functions.
 208 .PP
 209 There is no binding of a notion of an identity to a public key.
 210 .PP
 211 There is no trust level of a public key.  A reserved byte could be
 212 used for this, but the semantics then need to be designed.
 213 .SH NOTES ON CRYPTOGRAPHY
 214 The general methods described by SEC 1 Ver 2.0 were followed, but
 215 this is not an implementation of that scheme, because different
 216 algorithms are used.
 217 .SH FILES
 218 ~/.zpm/keys
 219 /var/lib/zpm/keys
 220 .SH ENVIRONMENT
 221 ZPM_KEYRING
 222 .SH AUTHOR
 223 Nathan Wagner
 224 .SH SEE ALSO
 225 .BR zpm (8)
 226 .R RFC
 227 .R http://www.secg.org SEC 1 Ver 2.0