move section on CA and revoked keys from ssh.1 to sshd.8's known hosts

format section and rework it a bit; requested by jmc@

2 files changed, 44 insertions, 41 deletions

diff --git a/usr.bin/ssh/ssh.1 b/usr.bin/ssh/ssh.1
index 8c53d4b0735..b201d87de80 100644
--- a/usr.bin/ssh/ssh.1
+++ b/usr.bin/ssh/ssh.1
@@ -34,7 +34,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.\" $OpenBSD: ssh.1,v 1.298 2010/03/04 12:51:25 jmc Exp $
+.\" $OpenBSD: ssh.1,v 1.299 2010/03/04 23:19:29 djm Exp $
 .Dd $Mdocdate: March 4 2010 $
 .Dt SSH 1
 .Os
@@ -1104,39 +1104,6 @@ option in
 .Xr ssh_config 5
 for more information.
 .Pp
-Host keys may also be presented as certificates signed by a trusted
-certification authority (CA).
-In this case, trust of the CA key alone is sufficient for the host key
-to be accepted.
-To specify a public key as a trusted CA key in a known hosts file,
-it should be added after a
-.Dq @cert-authority
-tag and a set of one or more domain-name wildcards separated by commas.
-For example:
-.Pp
-.Dl @cert-authority *.mydomain.org,*.mydomain.com ssh-rsa AAAAB5W...
-.Pp
-See the
-.Sx CERTIFICATES
-section of
-.Xr ssh-keygen 1
-for more details.
-.Pp
-Keys may also be marked as revoked using the
-.Dq @revoked
-marker.
-Revoked keys will always trigger a warning when encountered and the host
-that presented them will be treated as untrusted.
-For example:
-.Pp
-.Dl @revoked * ssh-rsa AAAAB5W...
-.Pp
-Revoking a key revokes it for direct use and as a certification authority.
-Do not use both the
-.Dq @cert-authority
-and
-.Dq @revoked
-markers on the same line.
 .Sh SSH-BASED VIRTUAL PRIVATE NETWORKS
 .Nm
 contains support for Virtual Private Network (VPN) tunnelling
diff --git a/usr.bin/ssh/sshd.8 b/usr.bin/ssh/sshd.8
index 0c169465f40..218c2049f79 100644
--- a/usr.bin/ssh/sshd.8
+++ b/usr.bin/ssh/sshd.8
@@ -34,8 +34,8 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.\" $OpenBSD: sshd.8,v 1.253 2010/03/03 22:49:50 djm Exp $
-.Dd $Mdocdate: March 3 2010 $
+.\" $OpenBSD: sshd.8,v 1.254 2010/03/04 23:19:29 djm Exp $
+.Dd $Mdocdate: March 4 2010 $
 .Dt SSHD 8
 .Os
 .Sh NAME
@@ -607,10 +607,19 @@ be prepared by the administrator (optional), and the per-user file is
 maintained automatically: whenever the user connects from an unknown host,
 its key is added to the per-user file.
 .Pp
-Each line in these files contains the following fields: hostnames,
-bits, exponent, modulus, comment.
+Each line in these files contains the following fields: markers (optional),
+hostnames, bits, exponent, modulus, comment.
 The fields are separated by spaces.
 .Pp
+The marker is optional, but if it is present then it must be one of
+.Dq @cert-authority ,
+to indicate that the line contains a certification authority (CA) key,
+or
+.Dq @revoked ,
+to indicate that the key contained on the line is revoked and must not ever
+be accepted.
+Only one marker should be used on a key line.
+.Pp
 Hostnames is a comma-separated list of patterns
 .Pf ( Ql *
 and
@@ -650,8 +659,25 @@ Lines starting with
 and empty lines are ignored as comments.
 .Pp
 When performing host authentication, authentication is accepted if any
-matching line has the proper key.
-It is thus permissible (but not
+matching line has the proper key; either one that matches exactly or,
+if the server has presented a certificate for authentication, the key
+of the certification authority that signed the certificate.
+For a key to be trusted as a certification authority, it must use the
+.Dq @cert-authority
+marker described above.
+.Pp
+The known hosts file also provides a facility to mark keys as revoked,
+for example when it is known that the associated private key has been
+stolen.
+Revoked keys are specified by including the
+.Dq @revoked
+marker at the beginning of the key line, and are never accepted for
+authentication or as certification authorities, but instead will
+produce a warning from
+.Xr ssh 1
+when they are encountered.
+.Pp
+It is permissible (but not
 recommended) to have several lines or different host keys for the same
 names.
 This will inevitably happen when short forms of host names
@@ -662,10 +688,16 @@ accepted if valid information can be found from either file.
 .Pp
 Note that the lines in these files are typically hundreds of characters
 long, and you definitely don't want to type in the host keys by hand.
-Rather, generate them by a script
+Rather, generate them by a script,
+.Xr ssh-keyscan 1
 or by taking
 .Pa /etc/ssh/ssh_host_key.pub
 and adding the host names at the front.
+.Xr ssh-keygen 1
+also offers some basic automated editing for 
+.Pa ~/.ssh/known_hosts
+including removing hosts matching a host name and converting all host
+names to their hashed representations.
 .Pp
 An example ssh_known_hosts file:
 .Bd -literal -offset 3n
@@ -675,6 +707,10 @@ cvs.example.net,192.0.2.10 ssh-rsa AAAA1234.....=
 # A hashed hostname
 |1|JfKTdBh7rNbXkVAQCRp4OQoPfmI=|USECr3SWf1JUPsms5AqfD5QfxkM= ssh-rsa
 AAAA1234.....=
+# A revoked key
+@revoked * ssh-rsa AAAAB5W...
+# A CA key, accepted for any host in *.mydomain.com or *.mydomain.org
+@cert-authority *.mydomain.org,*.mydomain.com ssh-rsa AAAAB5W...
 .Ed
 .Sh FILES
 .Bl -tag -width Ds -compact