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