diff options
author | djm@openbsd.org <djm@openbsd.org> | 2019-09-03 08:34:19 +0000 |
---|---|---|
committer | Damien Miller <djm@mindrot.org> | 2019-09-03 18:40:23 +1000 |
commit | 2a9c9f7272c1e8665155118fe6536bebdafb6166 (patch) | |
tree | 177a8c032d9396249708e4a5cb65321d9250fdee /ssh-keygen.1 | |
parent | 5485f8d50a5bc46aeed829075ebf5d9c617027ea (diff) |
upstream: sshsig: lightweight signature and verification ability
for OpenSSH
This adds a simple manual signature scheme to OpenSSH.
Signatures can be made and verified using ssh-keygen -Y sign|verify
Signatures embed the key used to make them. At verification time, this
is matched via principal name against an authorized_keys-like list
of allowed signers.
Mostly by Sebastian Kinne w/ some tweaks by me
ok markus@
OpenBSD-Commit-ID: 2ab568e7114c933346616392579d72be65a4b8fb
Diffstat (limited to 'ssh-keygen.1')
-rw-r--r-- | ssh-keygen.1 | 123 |
1 files changed, 121 insertions, 2 deletions
diff --git a/ssh-keygen.1 b/ssh-keygen.1 index b4bc336f2..93c76ef8a 100644 --- a/ssh-keygen.1 +++ b/ssh-keygen.1 | |||
@@ -1,4 +1,4 @@ | |||
1 | .\" $OpenBSD: ssh-keygen.1,v 1.162 2019/07/19 03:38:01 djm Exp $ | 1 | .\" $OpenBSD: ssh-keygen.1,v 1.163 2019/09/03 08:34:19 djm Exp $ |
2 | .\" | 2 | .\" |
3 | .\" Author: Tatu Ylonen <ylo@cs.hut.fi> | 3 | .\" Author: Tatu Ylonen <ylo@cs.hut.fi> |
4 | .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland | 4 | .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland |
@@ -35,7 +35,7 @@ | |||
35 | .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF | 35 | .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
36 | .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | 36 | .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
37 | .\" | 37 | .\" |
38 | .Dd $Mdocdate: July 19 2019 $ | 38 | .Dd $Mdocdate: September 3 2019 $ |
39 | .Dt SSH-KEYGEN 1 | 39 | .Dt SSH-KEYGEN 1 |
40 | .Os | 40 | .Os |
41 | .Sh NAME | 41 | .Sh NAME |
@@ -141,6 +141,18 @@ | |||
141 | .Fl Q | 141 | .Fl Q |
142 | .Fl f Ar krl_file | 142 | .Fl f Ar krl_file |
143 | .Ar | 143 | .Ar |
144 | .Nm ssh-keygen | ||
145 | .Fl Y Cm sign | ||
146 | .Fl f Ar key_file | ||
147 | .Fl n Ar namespace | ||
148 | .Ar | ||
149 | .Nm ssh-keygen | ||
150 | .Fl Y Cm verify | ||
151 | .Fl I Ar signer_identity | ||
152 | .Fl f Ar allowed_keys_file | ||
153 | .Fl n Ar namespace | ||
154 | .Fl s Ar signature_file | ||
155 | .Op Fl r Ar revocation_file | ||
144 | .Ek | 156 | .Ek |
145 | .Sh DESCRIPTION | 157 | .Sh DESCRIPTION |
146 | .Nm | 158 | .Nm |
@@ -649,6 +661,62 @@ Specify desired generator when testing candidate moduli for DH-GEX. | |||
649 | .It Fl y | 661 | .It Fl y |
650 | This option will read a private | 662 | This option will read a private |
651 | OpenSSH format file and print an OpenSSH public key to stdout. | 663 | OpenSSH format file and print an OpenSSH public key to stdout. |
664 | .It Fl Y Ar sign | ||
665 | Cryptographically sign a file or some data using a SSH key. | ||
666 | When signing, | ||
667 | .Nm | ||
668 | accepts zero or more files to sign on the command-line - if no files | ||
669 | are specified then | ||
670 | .Nm | ||
671 | will sign data presented on standard input. | ||
672 | Signatures are written to the path of the input file with | ||
673 | .Dq .sig | ||
674 | appended, or to standard output if the message to be signed was read from | ||
675 | standard input. | ||
676 | .Pp | ||
677 | The key used for signing is specified using the | ||
678 | .Fl f | ||
679 | option and may refer to either a private key, or a public key with the private | ||
680 | half available via | ||
681 | .Xr ssh-agent 1 . | ||
682 | An additional signature namespace, used to prevent signature confusion across | ||
683 | different domains of use (e.g. file signing vs email signing) must be provided | ||
684 | via the | ||
685 | .Fl n | ||
686 | flag. | ||
687 | Namespaces are arbitrary strings, and may include: | ||
688 | .Dq file | ||
689 | for file signing, | ||
690 | .Dq email | ||
691 | for email signing. | ||
692 | For custom uses, it is recommended to use names following a | ||
693 | NAMESPACE@YOUR.DOMAIN pattern to generate unambiguous namespaces. | ||
694 | .It Fl Y Ar verify | ||
695 | Request to verify a signature generated using | ||
696 | .Nm | ||
697 | .Fl Y sign | ||
698 | as described above. | ||
699 | When verifying a signature, | ||
700 | .Nm | ||
701 | accepts a message on standard input and a signature namespace using | ||
702 | .Fl n . | ||
703 | A file containing the corresponding signature must also be supplied using the | ||
704 | .Fl s | ||
705 | flag, along with the identity of the signer using | ||
706 | .Fl I | ||
707 | and a list of allowed signers via the | ||
708 | .Fl f | ||
709 | flag. | ||
710 | The format of the allowed signers file is documented in the | ||
711 | .Sx ALLOWED SIGNERS | ||
712 | section below. | ||
713 | A file containing revoked keys can be passed using the | ||
714 | .Fl r | ||
715 | flag. The revocation file may be a KRL or a one-per-line list | ||
716 | of public keys. | ||
717 | Successful verification by an authorized signer is signalled by | ||
718 | .Nm | ||
719 | returning a zero exit status. | ||
652 | .It Fl z Ar serial_number | 720 | .It Fl z Ar serial_number |
653 | Specifies a serial number to be embedded in the certificate to distinguish | 721 | Specifies a serial number to be embedded in the certificate to distinguish |
654 | this certificate from others from the same CA. | 722 | this certificate from others from the same CA. |
@@ -885,6 +953,57 @@ then | |||
885 | .Nm | 953 | .Nm |
886 | will exit with a non-zero exit status. | 954 | will exit with a non-zero exit status. |
887 | A zero exit status will only be returned if no key was revoked. | 955 | A zero exit status will only be returned if no key was revoked. |
956 | .Sh ALLOWED SIGNERS | ||
957 | When verifying signatures, | ||
958 | .Nm | ||
959 | uses a simple list of identities and keys to determine whether a signature | ||
960 | comes from an authorized source. | ||
961 | This "allowed signers" file uses a format patterned after the | ||
962 | AUTHORIZED_KEYS FILE FORMAT described in | ||
963 | .Xr sshd(8) . | ||
964 | Each line of the file contains the following space-separated fields: | ||
965 | principals, options, keytype, base64-encoded key. | ||
966 | Empty lines and lines starting with a | ||
967 | .Ql # | ||
968 | are ignored as comments. | ||
969 | .Pp | ||
970 | The principals field is a pattern-list (See PATTERNS in | ||
971 | .Xr ssh_config 5 ) | ||
972 | consisting of one or more comma-separated USER@DOMAIN identity patterns | ||
973 | that are accepted for signing. | ||
974 | When verifying, the identity presented via the | ||
975 | .Fl I option | ||
976 | must match a principals pattern in order for the corresponding key to be | ||
977 | considered acceptable for verification. | ||
978 | .Pp | ||
979 | The options (if present) consist of comma-separated option specifications. | ||
980 | No spaces are permitted, except within double quotes. | ||
981 | The following option specifications are supported (note that option keywords | ||
982 | are case-insensitive): | ||
983 | .Bl -tag -width Ds | ||
984 | .It Cm cert-authority | ||
985 | Indicates that this key is accepted as a certificate authority (CA) and | ||
986 | that certificates signed by this CA may be accepted for verification. | ||
987 | .It Cm namespaces="namespace-list" | ||
988 | Specifies a pattern-list of namespaces that are accepted for this key. | ||
989 | If this option is present, the the signature namespace embedded in the | ||
990 | signature object and presented on the verification command-line must | ||
991 | match the specified list before the key will be considered acceptable. | ||
992 | .El | ||
993 | .Pp | ||
994 | When verifying signatures made by certificates, the expected principal | ||
995 | name must match both the principals pattern in the allowed signers file and | ||
996 | the principals embedded in the certificate itself. | ||
997 | .Pp | ||
998 | An example allowed signers file: | ||
999 | .Bd -literal -offset 3n | ||
1000 | # Comments allowed at start of line | ||
1001 | user1@example.com,user2@example.com ssh-rsa AAAAX1... | ||
1002 | # A certificate authority, trusted for all principals in a domain. | ||
1003 | *@example.com cert-authority ssh-ed25519 AAAB4... | ||
1004 | # A key that is accepted only for file signing. | ||
1005 | user2@example.com namespaces="file" ssh-ed25519 AAA41... | ||
1006 | .Ed | ||
888 | .Sh FILES | 1007 | .Sh FILES |
889 | .Bl -tag -width Ds -compact | 1008 | .Bl -tag -width Ds -compact |
890 | .It Pa ~/.ssh/id_dsa | 1009 | .It Pa ~/.ssh/id_dsa |