Annotation of src/usr.bin/signify/signify.1, Revision 1.50
1.50 ! deraadt 1: .\" $OpenBSD: signify.1,v 1.49 2020/01/21 12:13:21 tb Exp $
1.1 tedu 2: .\"
3: .\"Copyright (c) 2013 Marc Espie <espie@openbsd.org>
4: .\"Copyright (c) 2013 Ted Unangst <tedu@openbsd.org>
5: .\"
6: .\"Permission to use, copy, modify, and distribute this software for any
7: .\"purpose with or without fee is hereby granted, provided that the above
8: .\"copyright notice and this permission notice appear in all copies.
9: .\"
10: .\"THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11: .\"WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12: .\"MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13: .\"ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14: .\"WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15: .\"ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16: .\"OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.50 ! deraadt 17: .Dd $Mdocdate: January 21 2020 $
1.1 tedu 18: .Dt SIGNIFY 1
19: .Os
20: .Sh NAME
21: .Nm signify
22: .Nd cryptographically sign and verify files
23: .Sh SYNOPSIS
24: .Nm signify
1.24 tedu 25: .Fl C
26: .Op Fl q
1.49 tb 27: .Op Fl p Ar pubkey
28: .Op Fl t Ar keytype
1.24 tedu 29: .Fl x Ar sigfile
1.25 naddy 30: .Op Ar
1.24 tedu 31: .Nm signify
1.10 deraadt 32: .Fl G
1.25 naddy 33: .Op Fl n
1.15 deraadt 34: .Op Fl c Ar comment
1.7 espie 35: .Fl p Ar pubkey
36: .Fl s Ar seckey
37: .Nm signify
1.10 deraadt 38: .Fl S
1.46 tedu 39: .Op Fl enz
1.19 tedu 40: .Op Fl x Ar sigfile
1.7 espie 41: .Fl s Ar seckey
1.19 tedu 42: .Fl m Ar message
1.7 espie 43: .Nm signify
1.10 deraadt 44: .Fl V
1.35 espie 45: .Op Fl eqz
46: .Op Fl p Ar pubkey
47: .Op Fl t Ar keytype
1.19 tedu 48: .Op Fl x Ar sigfile
49: .Fl m Ar message
1.1 tedu 50: .Sh DESCRIPTION
51: The
52: .Nm
1.19 tedu 53: utility creates and verifies cryptographic signatures.
54: A signature verifies the integrity of a
1.8 tedu 55: .Ar message .
1.10 deraadt 56: The mode of operation is selected with the following options:
1.12 tedu 57: .Bl -tag -width Dsssigfile
1.24 tedu 58: .It Fl C
1.25 naddy 59: Verify a signed checksum list, and then verify the checksum for
1.24 tedu 60: each file.
61: If no files are specified, all of them are checked.
62: .Ar sigfile
63: should be the signed output of
64: .Xr sha256 1 .
1.10 deraadt 65: .It Fl G
1.25 naddy 66: Generate a new key pair.
1.40 tedu 67: Keynames should follow the convention of
68: .Pa keyname.pub
69: and
70: .Pa keyname.sec
71: for the public and secret keys, respectively.
1.10 deraadt 72: .It Fl S
1.19 tedu 73: Sign the specified message file and create a signature.
1.10 deraadt 74: .It Fl V
1.19 tedu 75: Verify the message and signature match.
1.10 deraadt 76: .El
1.4 jmc 77: .Pp
1.10 deraadt 78: The other options are as follows:
1.12 tedu 79: .Bl -tag -width Dsssignature
1.14 tedu 80: .It Fl c Ar comment
81: Specify the comment to be added during key generation.
1.8 tedu 82: .It Fl e
1.19 tedu 83: When signing, embed the message after the signature.
84: When verifying, extract the message from the signature.
85: (This requires that the signature was created using
86: .Fl e
87: and creates a new message file as output.)
88: .It Fl m Ar message
89: When signing, the file containing the message to sign.
90: When verifying, the file containing the message to verify.
91: When verifying with
92: .Fl e ,
93: the file to create.
1.6 tedu 94: .It Fl n
1.46 tedu 95: When generating a key pair, do not ask for a passphrase.
1.1 tedu 96: Otherwise,
97: .Nm
1.19 tedu 98: will prompt the user for a passphrase to protect the secret key.
1.46 tedu 99: When signing with
100: .Fl z ,
101: store a zero time stamp in the
102: .Xr gzip 1
103: header.
1.6 tedu 104: .It Fl p Ar pubkey
1.1 tedu 105: Public key produced by
1.7 espie 106: .Fl G ,
1.1 tedu 107: and used by
1.7 espie 108: .Fl V
1.1 tedu 109: to check a signature.
1.24 tedu 110: .It Fl q
1.25 naddy 111: Quiet mode.
112: Suppress informational output.
1.6 tedu 113: .It Fl s Ar seckey
1.1 tedu 114: Secret (private) key produced by
1.7 espie 115: .Fl G ,
1.1 tedu 116: and used by
1.7 espie 117: .Fl S
1.1 tedu 118: to sign a message.
1.35 espie 119: .It Fl t Ar keytype
120: When deducing the correct key to check a signature, make sure
121: the actual key matches
1.39 tedu 122: .Pa /etc/signify/*-keytype.pub .
1.19 tedu 123: .It Fl x Ar sigfile
124: The signature file to create or verify.
125: The default is
126: .Ar message Ns .sig .
1.35 espie 127: .It Fl z
128: Sign and verify
129: .Xr gzip 1
130: archives, where the signing data
131: is embedded in the
132: .Xr gzip 1
133: header.
1.1 tedu 134: .El
1.4 jmc 135: .Pp
136: The key and signature files created by
137: .Nm
138: have the same format.
139: The first line of the file is a free form text comment that may be edited,
140: so long as it does not exceed a single line.
1.40 tedu 141: Signature comments will be generated based on the name of the secret
142: key used for signing.
143: This comment can then be used as a hint for the name of the public key
144: when verifying.
1.4 jmc 145: The second line of the file is the actual key or signature base64 encoded.
1.1 tedu 146: .Sh EXIT STATUS
1.4 jmc 147: .Ex -std signify
148: It may fail because of one of the following reasons:
149: .Pp
1.1 tedu 150: .Bl -bullet -compact
1.4 jmc 151: .It
1.1 tedu 152: Some necessary files do not exist.
153: .It
154: Entered passphrase is incorrect.
155: .It
156: The message file was corrupted and its signature does not match.
157: .It
158: The message file is too large.
159: .El
160: .Sh EXAMPLES
1.25 naddy 161: Create a new key pair:
1.7 espie 162: .Dl $ signify -G -p newkey.pub -s newkey.sec
1.4 jmc 163: .Pp
164: Sign a file, specifying a signature name:
1.19 tedu 165: .Dl $ signify -S -s key.sec -m message.txt -x msg.sig
1.4 jmc 166: .Pp
1.1 tedu 167: Verify a signature, using the default signature name:
1.19 tedu 168: .Dl $ signify -V -p key.pub -m generalsorders.txt
1.11 deraadt 169: .Pp
1.17 deraadt 170: Verify a release directory containing
1.19 tedu 171: .Pa SHA256.sig
1.17 deraadt 172: and a full set of release files:
1.21 jmc 173: .Bd -literal -offset indent -compact
1.50 ! deraadt 174: $ signify -C -p /etc/signify/openbsd-68-base.pub -x SHA256.sig
1.22 lteo 175: .Ed
176: .Pp
177: Verify a bsd.rd before an upgrade:
178: .Bd -literal -offset indent -compact
1.50 ! deraadt 179: $ signify -C -p /etc/signify/openbsd-68-base.pub -x SHA256.sig bsd.rd
1.21 jmc 180: .Ed
1.35 espie 181: .Pp
182: Sign a gzip archive:
183: .Bd -literal -offset indent -compact
184: $ signify -Sz -s key-arc.sec -m in.tgz -x out.tgz
185: .Ed
186: .Pp
187: Verify a gzip pipeline:
188: .Bd -literal -offset indent -compact
1.38 tedu 189: $ ftp url | signify -Vz -t arc | tar ztf -
1.35 espie 190: .Ed
1.1 tedu 191: .Sh SEE ALSO
1.11 deraadt 192: .Xr fw_update 1 ,
1.36 espie 193: .Xr gzip 1 ,
1.11 deraadt 194: .Xr pkg_add 1 ,
1.47 tedu 195: .Xr sha256 1 ,
196: .Xr sysupgrade 8
1.1 tedu 197: .Sh HISTORY
198: The
199: .Nm
200: command first appeared in
1.7 espie 201: .Ox 5.5 .
1.30 tedu 202: .Sh AUTHORS
1.36 espie 203: .An -nosplit
204: .An Ted Unangst Aq Mt tedu@openbsd.org
205: and
1.37 jmc 206: .An Marc Espie Aq Mt espie@openbsd.org .