Annotation of src/usr.bin/signify/signify.1, Revision 1.39
1.39 ! tedu 1: .\" $OpenBSD: signify.1,v 1.38 2016/09/02 21:04:26 tedu 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.36 espie 17: .Dd $Mdocdate: September 2 2016 $
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
27: .Fl p Ar pubkey
28: .Fl x Ar sigfile
1.25 naddy 29: .Op Ar
1.24 tedu 30: .Nm signify
1.10 deraadt 31: .Fl G
1.25 naddy 32: .Op Fl n
1.15 deraadt 33: .Op Fl c Ar comment
1.7 espie 34: .Fl p Ar pubkey
35: .Fl s Ar seckey
36: .Nm signify
1.10 deraadt 37: .Fl S
1.35 espie 38: .Op Fl ez
1.19 tedu 39: .Op Fl x Ar sigfile
1.7 espie 40: .Fl s Ar seckey
1.19 tedu 41: .Fl m Ar message
1.7 espie 42: .Nm signify
1.10 deraadt 43: .Fl V
1.35 espie 44: .Op Fl eqz
45: .Op Fl p Ar pubkey
46: .Op Fl t Ar keytype
1.19 tedu 47: .Op Fl x Ar sigfile
48: .Fl m Ar message
1.1 tedu 49: .Sh DESCRIPTION
50: The
51: .Nm
1.19 tedu 52: utility creates and verifies cryptographic signatures.
53: A signature verifies the integrity of a
1.8 tedu 54: .Ar message .
1.10 deraadt 55: The mode of operation is selected with the following options:
1.12 tedu 56: .Bl -tag -width Dsssigfile
1.24 tedu 57: .It Fl C
1.25 naddy 58: Verify a signed checksum list, and then verify the checksum for
1.24 tedu 59: each file.
60: If no files are specified, all of them are checked.
61: .Ar sigfile
62: should be the signed output of
63: .Xr sha256 1 .
1.10 deraadt 64: .It Fl G
1.25 naddy 65: Generate a new key pair.
1.10 deraadt 66: .It Fl S
1.19 tedu 67: Sign the specified message file and create a signature.
1.10 deraadt 68: .It Fl V
1.19 tedu 69: Verify the message and signature match.
1.10 deraadt 70: .El
1.4 jmc 71: .Pp
1.10 deraadt 72: The other options are as follows:
1.12 tedu 73: .Bl -tag -width Dsssignature
1.14 tedu 74: .It Fl c Ar comment
75: Specify the comment to be added during key generation.
1.8 tedu 76: .It Fl e
1.19 tedu 77: When signing, embed the message after the signature.
78: When verifying, extract the message from the signature.
79: (This requires that the signature was created using
80: .Fl e
81: and creates a new message file as output.)
82: .It Fl m Ar message
83: When signing, the file containing the message to sign.
84: When verifying, the file containing the message to verify.
85: When verifying with
86: .Fl e ,
87: the file to create.
1.6 tedu 88: .It Fl n
1.1 tedu 89: Do not ask for a passphrase during key generation.
90: Otherwise,
91: .Nm
1.19 tedu 92: will prompt the user for a passphrase to protect the secret key.
1.6 tedu 93: .It Fl p Ar pubkey
1.1 tedu 94: Public key produced by
1.7 espie 95: .Fl G ,
1.1 tedu 96: and used by
1.7 espie 97: .Fl V
1.1 tedu 98: to check a signature.
1.24 tedu 99: .It Fl q
1.25 naddy 100: Quiet mode.
101: Suppress informational output.
1.6 tedu 102: .It Fl s Ar seckey
1.1 tedu 103: Secret (private) key produced by
1.7 espie 104: .Fl G ,
1.1 tedu 105: and used by
1.7 espie 106: .Fl S
1.1 tedu 107: to sign a message.
1.35 espie 108: .It Fl t Ar keytype
109: When deducing the correct key to check a signature, make sure
110: the actual key matches
1.39 ! tedu 111: .Pa /etc/signify/*-keytype.pub .
1.19 tedu 112: .It Fl x Ar sigfile
113: The signature file to create or verify.
114: The default is
115: .Ar message Ns .sig .
1.35 espie 116: .It Fl z
117: Sign and verify
118: .Xr gzip 1
119: archives, where the signing data
120: is embedded in the
121: .Xr gzip 1
122: header.
1.1 tedu 123: .El
1.4 jmc 124: .Pp
125: The key and signature files created by
126: .Nm
127: have the same format.
128: The first line of the file is a free form text comment that may be edited,
129: so long as it does not exceed a single line.
1.26 tedu 130: .\" Signature comments will be generated based on the name of the secret
131: .\" key used for signing.
132: .\" This comment can then be used as a hint for the name of the public key
133: .\" when verifying.
1.4 jmc 134: The second line of the file is the actual key or signature base64 encoded.
1.1 tedu 135: .Sh EXIT STATUS
1.4 jmc 136: .Ex -std signify
137: It may fail because of one of the following reasons:
138: .Pp
1.1 tedu 139: .Bl -bullet -compact
1.4 jmc 140: .It
1.1 tedu 141: Some necessary files do not exist.
142: .It
143: Entered passphrase is incorrect.
144: .It
145: The message file was corrupted and its signature does not match.
146: .It
147: The message file is too large.
148: .El
149: .Sh EXAMPLES
1.25 naddy 150: Create a new key pair:
1.7 espie 151: .Dl $ signify -G -p newkey.pub -s newkey.sec
1.4 jmc 152: .Pp
153: Sign a file, specifying a signature name:
1.19 tedu 154: .Dl $ signify -S -s key.sec -m message.txt -x msg.sig
1.4 jmc 155: .Pp
1.1 tedu 156: Verify a signature, using the default signature name:
1.19 tedu 157: .Dl $ signify -V -p key.pub -m generalsorders.txt
1.11 deraadt 158: .Pp
1.17 deraadt 159: Verify a release directory containing
1.19 tedu 160: .Pa SHA256.sig
1.17 deraadt 161: and a full set of release files:
1.21 jmc 162: .Bd -literal -offset indent -compact
1.34 deraadt 163: $ signify -C -p /etc/signify/openbsd-61-base.pub -x SHA256.sig
1.22 lteo 164: .Ed
165: .Pp
166: Verify a bsd.rd before an upgrade:
167: .Bd -literal -offset indent -compact
1.34 deraadt 168: $ signify -C -p /etc/signify/openbsd-61-base.pub -x SHA256.sig bsd.rd
1.21 jmc 169: .Ed
1.35 espie 170: .Pp
171: Sign a gzip archive:
172: .Bd -literal -offset indent -compact
173: $ signify -Sz -s key-arc.sec -m in.tgz -x out.tgz
174: .Ed
175: .Pp
176: Verify a gzip pipeline:
177: .Bd -literal -offset indent -compact
1.38 tedu 178: $ ftp url | signify -Vz -t arc | tar ztf -
1.35 espie 179: .Ed
1.1 tedu 180: .Sh SEE ALSO
1.11 deraadt 181: .Xr fw_update 1 ,
1.36 espie 182: .Xr gzip 1 ,
1.11 deraadt 183: .Xr pkg_add 1 ,
1.36 espie 184: .Xr sha256 1
1.1 tedu 185: .Sh HISTORY
186: The
187: .Nm
188: command first appeared in
1.7 espie 189: .Ox 5.5 .
1.30 tedu 190: .Sh AUTHORS
1.36 espie 191: .An -nosplit
192: .An Ted Unangst Aq Mt tedu@openbsd.org
193: and
1.37 jmc 194: .An Marc Espie Aq Mt espie@openbsd.org .