ssh-vulnkey.1

   1 .\" Copyright (c) 2008 Canonical Ltd.  All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  13 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  14 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  15 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  16 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  17 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  18 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  19 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  20 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  21 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  22 .\"
  23 .Dd $Mdocdate: May 12 2008 $
  24 .Dt SSH-VULNKEY 1
  25 .Os
  26 .Sh NAME
  27 .Nm ssh-vulnkey
  28 .Nd check blacklist of compromised keys
  29 .Sh SYNOPSIS
  30 .Nm
  31 .Op Fl q | Fl v
  32 .Ar file ...
  33 .Nm
  34 .Fl a
  35 .Sh DESCRIPTION
  36 .Nm
  37 checks a key against a blacklist of compromised keys.
  38 .Pp
  39 A substantial number of keys are known to have been generated using a broken
  40 version of OpenSSL distributed by Debian which failed to seed its random
  41 number generator correctly.
  42 Keys generated using these OpenSSL versions should be assumed to be
  43 compromised.
  44 This tool may be useful in checking for such keys.
  45 .Pp
  46 Keys that are compromised cannot be repaired; replacements must be generated
  47 using
  48 .Xr ssh-keygen 1 .
  49 Make sure to update
  50 .Pa authorized_keys
  51 files on all systems where compromised keys were permitted to authenticate.
  52 .Pp
  53 The argument list will be interpreted as a list of paths to public key files
  54 or
  55 .Pa authorized_keys
  56 files.
  57 If no suitable file is found at a given path,
  58 .Nm
  59 will append
  60 .Pa .pub
  61 and retry, in case it was given a private key file.
  62 If no files are given as arguments,
  63 .Nm
  64 will check
  65 .Pa ~/.ssh/id_rsa ,
  66 .Pa ~/.ssh/id_dsa ,
  67 .Pa ~/.ssh/identity ,
  68 .Pa ~/.ssh/authorized_keys
  69 and
  70 .Pa ~/.ssh/authorized_keys2 ,
  71 as well as the system's host keys if readable.
  72 .Pp
  73 If
  74 .Dq -
  75 is given as an argument,
  76 .Nm
  77 will read from standard input.
  78 This can be used to process output from
  79 .Xr ssh-keyscan 1 ,
  80 for example:
  81 .Pp
  82 .Dl $ ssh-keyscan -t rsa remote.example.org | ssh-vulnkey -
  83 .Pp
  84 Unless the
  85 .Cm PermitBlacklistedKeys
  86 option is used,
  87 .Xr sshd 8
  88 will reject attempts to authenticate with keys in the compromised list.
  89 .Pp
  90 The output from
  91 .Nm
  92 looks like this:
  93 .Pp
  94 .Bd -literal -offset indent
  95 /etc/ssh/ssh_host_key:1: COMPROMISED: RSA1 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx root@host
  96 /home/user/.ssh/id_dsa:1: Not blacklisted: DSA 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx /home/user/.ssh/id_dsa.pub
  97 /home/user/.ssh/authorized_keys:3: Unknown (blacklist file not installed): RSA 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx user@host
  98 .Ed
  99 .Pp
 100 Each line is of the following format (any lines beginning with
 101 .Dq #
 102 should be ignored by scripts):
 103 .Pp
 104 .Dl Ar filename : Ns Ar line : Ar status : Ar type Ar size Ar fingerprint Ar comment
 105 .Pp
 106 It is important to distinguish between the possible values of
 107 .Ar status :
 108 .Pp
 109 .Bl -tag -width Ds
 110 .It COMPROMISED
 111 These keys are listed in a blacklist file, normally because their
 112 corresponding private keys are well-known.
 113 Replacements must be generated using
 114 .Xr ssh-keygen 1 .
 115 .It Not blacklisted
 116 A blacklist file exists for this key type and size, but this key is not
 117 listed in it.
 118 Unless there is some particular reason to believe otherwise, this key
 119 may be used safely.
 120 (Note that DSA keys used with the broken version of OpenSSL distributed
 121 by Debian may be compromised in the event that anyone captured a network
 122 trace, even if they were generated with a secure version of OpenSSL.)
 123 .It Unknown (blacklist file not installed)
 124 No blacklist file exists for this key type and size.
 125 You should find a suitable published blacklist and install it before
 126 deciding whether this key is safe to use.
 127 .El
 128 .Pp
 129 The options are as follows:
 130 .Bl -tag -width Ds
 131 .It Fl a
 132 Check keys of all users on the system.
 133 You will typically need to run
 134 .Nm
 135 as root to use this option.
 136 For each user,
 137 .Nm
 138 will check
 139 .Pa ~/.ssh/id_rsa ,
 140 .Pa ~/.ssh/id_dsa ,
 141 .Pa ~/.ssh/identity ,
 142 .Pa ~/.ssh/authorized_keys
 143 and
 144 .Pa ~/.ssh/authorized_keys2 .
 145 It will also check the system's host keys.
 146 .It Fl q
 147 Quiet mode.
 148 Normally,
 149 .Nm
 150 outputs the fingerprint of each key scanned, with a description of its
 151 status.
 152 This option suppresses that output.
 153 .It Fl v
 154 Verbose mode.
 155 Normally,
 156 .Nm
 157 does not output anything for keys that are not listed in their corresponding
 158 blacklist file (although it still produces output for keys for which there
 159 is no blacklist file, since their status is unknown).
 160 This option causes
 161 .Nm
 162 to produce output for all keys.
 163 .El
 164 .Sh EXIT STATUS
 165 .Nm
 166 will exit zero if any of the given keys were in the compromised list,
 167 otherwise non-zero.
 168 .Sh BLACKLIST FILE FORMAT
 169 The blacklist file may start with comments, on lines starting with
 170 .Dq # .
 171 After these initial comments, it must follow a strict format:
 172 .Pp
 173 .Bl -bullet -offset indent -compact
 174 .It
 175 All the lines must be exactly the same length (20 characters followed by a
 176 newline) and must be in sorted order.
 177 .It
 178 Each line must consist of the lower-case hexadecimal MD5 key fingerprint,
 179 without colons, and with the first 12 characters removed (that is, the least
 180 significant 80 bits of the fingerprint).
 181 .El
 182 .Pp
 183 The key fingerprint may be generated using
 184 .Xr ssh-keygen 1 :
 185 .Pp
 186 .Dl $ ssh-keygen -l -f /path/to/key
 187 .Pp
 188 This strict format is necessary to allow the blacklist file to be checked
 189 quickly, using a binary-search algorithm.
 190 .Sh FILES
 191 .Bl -tag -width Ds
 192 .It Pa ~/.ssh/id_rsa
 193 If present, contains the protocol version 2 RSA authentication identity of
 194 the user.
 195 .It Pa ~/.ssh/id_dsa
 196 If present, contains the protocol version 2 DSA authentication identity of
 197 the user.
 198 .It Pa ~/.ssh/identity
 199 If present, contains the protocol version 1 RSA authentication identity of
 200 the user.
 201 .It Pa ~/.ssh/authorized_keys
 202 If present, lists the public keys (RSA/DSA) that can be used for logging in
 203 as this user.
 204 .It Pa ~/.ssh/authorized_keys2
 205 Obsolete name for
 206 .Pa ~/.ssh/authorized_keys .
 207 This file may still be present on some old systems, but should not be
 208 created if it is missing.
 209 .It Pa /etc/ssh/ssh_host_rsa_key
 210 If present, contains the protocol version 2 RSA identity of the system.
 211 .It Pa /etc/ssh/ssh_host_dsa_key
 212 If present, contains the protocol version 2 DSA identity of the system.
 213 .It Pa /etc/ssh/ssh_host_key
 214 If present, contains the protocol version 1 RSA identity of the system.
 215 .It Pa /usr/share/ssh/blacklist. Ns Ar TYPE Ns Pa - Ns Ar LENGTH
 216 If present, lists the blacklisted keys of type
 217 .Ar TYPE
 218 .Pf ( Dq RSA
 219 or
 220 .Dq DSA )
 221 and bit length
 222 .Ar LENGTH .
 223 The format of this file is described above.
 224 RSA1 keys are converted to RSA before being checked in the blacklist.
 225 Note that the fingerprints of RSA1 keys are computed differently, so you
 226 will not be able to find them in the blacklist by hand.
 227 .It Pa /etc/ssh/blacklist. Ns Ar TYPE Ns Pa - Ns Ar LENGTH
 228 Same as
 229 .Pa /usr/share/ssh/blacklist. Ns Ar TYPE Ns Pa - Ns Ar LENGTH ,
 230 but may be edited by the system administrator to add new blacklist entries.
 231 .El
 232 .Sh SEE ALSO
 233 .Xr ssh-keygen 1 ,
 234 .Xr sshd 8
 235 .Sh AUTHORS
 236 .An -nosplit
 237 .An Colin Watson Aq cjwatson@ubuntu.com
 238 .Pp
 239 Florian Weimer suggested the option to check keys of all users, and the idea
 240 of processing
 241 .Xr ssh-keyscan 1
 242 output.