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

   1 .TH zpm-sign 8 2019-03-09 "ZPM 0.7.0"
   2 .SH NAME
   3 zpm-sign \- manage package signatures
   4 .SH SYNOPSIS
   5 .B zpm sign
   6 [
   7 .B \-vsge
   8 ]
   9 [
  10 .B \-Hhrd
  11 ]
  12 [
  13 .BI -o " outfile"
  14 ]
  15 [
  16 .BI -i " input"
  17 ]
  18 [
  19 .BI -k " keyid"
  20 ]
  21 [
  22 .BI -I " inputhexstring"
  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.
  37 .PP
  38 Private keys are potentially encrypted with chacha20 before storing
  39 them on disk.
  40 .PP
  41 Signatures are always detached signatures.
  42 .SS Specifying a key
  43 The \-k option is used to specify a key.  Keys are looked for
  44 in the keyring file (or taken literally from the command line
  45 if the \-h option is given).
  46 The \-i option can be used to specify a
  47 key file to look for a key in.  If the \-k option is given, or the ZPM_KEY
  48 environment variable is set, a key which matches that string in the id portion
  49 of the key is looked for, otherwise the first secret key found is used.  If the
  50 \-i option is not given, a key will be searched for in a file given with the
  51 ZPM_KEYFILE environment variable or in ~/.zpm/key  Alternatively, a hex encoded
  52 private key can be specified directly with the \-I option.  If several of these
  53 options apply, The \-I option takes precedence.  I.e. command line beats
  54 environment variables beats defaults.
  55 .PP
  56 If the private key needs a passphrase, it can be specified via the \-p
  57 option or the ZPM_KEYPASS environment variable, neither of which
  58 is secure.  Otherwise, if /dev/tty can be opened, zpm-sign will
  59 attempt to ask for a passphrase.
  60 .PP
  61 For signing or generating a public key, a private key is looked for, and if not
  62 specified, the first one found in the keyring file is used.
  63 .PP
  64 For signature verification, no key needs to be specified as the public
  65 key is contained in the signature.
  66 .SS Signing Mode
  67 To sign data, use \-s
  68 .PP
  69 Inputs to a regular signature are:
  70 .TP  the secret key used to sign the message,
  71 See above for methods to specify a secret key.
  72 .TP
  73 Signature timestamp
  74 Defaults to the current time read from the system clock.
  75 Can be specified with the \-T option.
  76 .TP
  77 Expiration timestamp
  78 Defaults to never.  Can be specified with the \-E optino.
  79 .TP
  80 The message to be signed.
  81 Is read from stdin, a command line argument, or the \-m option.
  82 If both an argument and a \-m option are given the \-m option wins.
  83 .PP
  84 When a raw signature is created (with the \-r option), the
  85 .PP
  86 The signature is output to stdout, or the output file given with the
  87 \-o option.  A signature packet is output unless the \-b option is given,
  88 in which case only the hex encoded signature is output.
  89 .SS Key Generation Mode
  90 A new private key is generated with \-g
  91 .SS Verification Mode
  92 A signature can be verified with \-v
  93 .SH OPTIONS
  94 .TP
  95 .B -r
  96 Output the raw signature or key data without wrapping it in a
  97 packet structure.
  98 .TP
  99 .B \-g
 100 Generate a private key
 101 .TP
 102 .B \-e
 103 Extract a public key from a private key.
 104 .TP
 105 .B \-s
 106 Sign a file or message.  In addition to the message to be signed,
 107 signature metadata is signed.
 108 .TP
 109 .B \-v
 110 Verify a signature on a file or message.
 111 .TP
 112 .B \-h
 113 hexencode values
 114 .TP
 115 .B \-d
 116 Increase the debug level.  May be given more than once.
 117 .TP
 118 .B \-r
 119 Output the raw signature, rather than a full zpm certificate.
 120 This also just signs the data given, without any signature
 121 metadata.
 122 .TP
 123 .BI \-p " passphrase"
 124 Specify a passphrase to decrypt or encrypt a private key.  If not given here,
 125 the environment variable ZPM_SIGN_PP is used.  Neither of these options
 126 are very secure, the command line in particular is generally readable
 127 by other processes.
 128 .TP
 129 .BI \-m " message"
 130 Specify a message to be signed or verified.  If not set with the -m option, the
 131 message is taken from file named with the first non-option argument.
 132 .TP
 133 .BI \-k " path"
 134 Take the private key for message signing from the path given.  This
 135 defaults to ~/.zpm/key.  If ~/.zpm/key is not found and the euid
 136 is root, /var/lib/zpm/key is tried.
 137 .TP
 138 .BI \-K " key"
 139 Take the private key from the command line argument.  This is not
 140 particularly secure and is primarily intended for testing.
 141 .TP
 142 .BI \-S " sigstring"
 143 Use sigstring as the signature to verify.
 144 .TP
 145 .BI \-m " message"
 146 Specify a message to be signed or verified.  If not set with the -m option, the
 147 message is taken from file named with the first non-option argument.
 148 .TP
 149 .BI \-t " timestamp"
 150 Specify a timestamp to be used for signing instead of the current time.
 151 Must be specified as a decimal representation of the unix timestamp
 152 to be used.
 153 .SH PACKET AND FILE FORMAT
 154 .PP
 155 Signatures and keys are output as hexencoded packet bytestrings.  All are 256
 156 bytes, (512 bytes as hex encoded).  Reserved bytes in packet formats must be
 157 zero.  The last 8 bytes are reserved.
 158 .PP
 159 On disk format is a series of 32 bytes, hex encoded, followed by
 160 a newline.  This takes one line per 32 bytes, thus 4 lines for 128,
 161 8 lines for 256.  If we waste 8 bytes at the end, we have 8 lines
 162 and 512 bytes encoded, the last line will be short by 16 characters,
 163 so that the actual size on disk is 512 bytes.
 164 .PP
 165 Timestamps are 8 byte little endian integers of seconds since the epoch.  or
 166 unix time, or some such.  Times are a mess.  Unix time is leap second unaware,
 167 and ambiguous during leap seconds.  UTC requires a database of leap seconds for
 168 past time, and the specified second in the future possibly changes.  TAI is
 169 good, but currently 37 seconds behind UTC, which is just weird.
 170 .PP
 171 All key and signature data begin with an 8 byte header, consisting of
 172 the following:
 173 .EX
 174 5A 50 4D 53 = "ZPMS" in ascii.
 175 01          = one byte version number
 176 xx          = one byte packet type
 177 xx xx       = two bytes packet information
 178 .EE
 179 .PP
 180 There are the following packet types.
 181 .SS Private Keys
 182 The public key is derivable from the secret key, so the public key is not
 183 explicitly stored.
 184 .EX
 185 private key format is:
 186 "ZPMS" 4 byte magic "ZPMS"
 187 byte 0x01 = version 1
 188 byte 0x01 = private key
 189 byte 0x01 = chacha encrypted, 0x00 = plain/raw key bytes
 190 byte 0x00 reserved, probably "key usage"
 191 32 bytes private key
 192 8 bytes creation time, little endian
 193 8 bytes expiration time, little endian
 194 8 bytes password salt, note, nist wants 16, but we're not using nist
 195 approved hash algorithms anyway.
 196 64 bytes reserved
 197 could have 16 bytes of IV for chacha to encrypt.
 198 Can probably use those, hashed with the password as the salt, but
 199 not very much salt then.
 200 120 bytes id
 201 8 bytes reserved trailer
 202 .EE
 203 .SS Public Keys
 204 .EX
 205 public key format is:
 206 "ZPMS" 4 byte magic "ZPMS"
 207 0x01   1 byte version
 208 0x02   1 byte "public key packet"
 209 0x00   1 byte reserved
 210 0x00   1 byte reserved
 211 0x..  32 bytes public key
 212 0x..  24 bytes reserved : create, expire, 8 reserved
 213 0x..  64 bytes reserved : self sig
 214      120 bytes reserved : id = 1 byte id length, n bytes id, zeros
 215        8 bytes reserved trailer
 216 0x..     revocation signatures
 217 0x..     user id packets
 218 0x..     certification signatures
 219 0x..     sub key packets
 220 .EE
 221 .SS Signatures
 222 Data, Key, and Revocation signatures all have the same format,
 223 with the exception of the packet type byte at offset 5.  Type
 224 0x03 is a data signature used for signing arbitrary data.  Type
 225 0x04 is a key signature used to sign public keys.  Type 0x05 is
 226 a revocation signature, used to revoke signatures.
 227 .EX
 228 "ZPMS" 4 byte magic "ZPMS"
 229 0x01   1 byte version
 230 0x03   1 byte "signature packet"
 231 0x00   1 byte reserved
 232 0x00   1 byte reserved
 233 0x..   8 bytes timestamp of signature time
 234 0x..   8 bytes timestamp of signature expiration, 0 if none
 235 0x..  64 bytes of actual signature
 236 0x..  32 bytes of public key making the signature
 237 0x..   8 bytes reserved
 238      120 bytes reserved
 239        8 bytes reserved trailer
 240 .EE
 241 .SH EXAMPLES
 242 .TP
 243 .B zpm sign -s \fIpath\fR
 244 Sign the contents of the file found at \fIpath\fR using the default secret key
 245 with a signing timestamp of the current time and no expiration date.  The
 246 signature packet will be written to stdout.
 247 .TP
 248 .B zpm sign -s -m 'foo'
 249 Sign the string 'foo'.
 250 .TP
 251 .B printf '%s' foo | zpm sign -s
 252 Sign the string 'foo' as in the above example, the message being read
 253 from stdin.
 254 .TP
 255 .B zpm sign -s -r -m 'foo'
 256 Sign the string 'foo' directly using the default private key, no
 257 additional information is signed, and the output is a hex encoded
 258 raw signature with no additional newlines, making up 128 characters
 259 of output.  There is no way to output just the raw signature while
 260 still adding the timestamps and such, but the raw signature can be
 261 extracted from a signature packet.
 262 .TP
 263 .B zpm sign -s -r \\
 264 -I 'c5aa8df43f9f837bedb7442f31dcb7b166d38535076f094b85ce3a2e0b4458f7' \\
 265 -h -m 'af82'
 266 Sign the two byte hex encoded message af82 with the raw hex encoded
 267 secret key given by the -I argument.  The result will be
 268 6291d657deec24024827e69c3abe01a30ce548a284743a445e3680d7db5ac3ac
 269 18ff9b538d16f290ae67f760984dc6594a7c15e9716ed28dc027beceea1ec40a
 270 all on a single line with no trailing newline.
 271 .SH EXIT STATUS
 272 0 on success non zero on failure
 273 .SH BUGS
 274 .PP
 275 Timestamps are a mess.  Unix time is leap second unaware, and ambiguous during
 276 leap seconds.  UTC requires a database of leap seconds for past time, and the
 277 specified second in the future possibly changes.  TAI is good, but currently 37
 278 seconds behind UTC, which is just weird.  Regardless of the above, unix
 279 time was chosen for general compatibility with time functions.
 280 .PP
 281 There is no binding of a notion of an identity to a public key.
 282 .PP
 283 There is no trust level of a public key.  A reserved byte could be
 284 used for this, but the semantics then need to be designed.
 285 .SH NOTES ON CRYPTOGRAPHY
 286 The general methods described by SEC 1 Ver 2.0 were followed, but
 287 this is not an implementation of that scheme, because different
 288 algorithms are used.
 289 .PP
 290 Chacha20 is used to encrypt private keys.
 291 .SH FILES
 292 ~/.zpm/keys
 293 /var/lib/zpm/keys
 294 .SH ENVIRONMENT
 295 ZPM_KEYRING
 296 .SH AUTHOR
 297 Nathan Wagner
 298 .SH SEE ALSO
 299 .BR zpm (8)
 300 .R RFC
 301 .R http://www.secg.org SEC 1 Ver 2.0