469 lines
14 KiB
Groff
469 lines
14 KiB
Groff
.\" $OpenBSD: ssh-keygen.1,v 1.78 2008/06/12 19:10:09 jmc Exp $
|
|
.\"
|
|
.\" -*- nroff -*-
|
|
.\"
|
|
.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
|
|
.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
|
|
.\" All rights reserved
|
|
.\"
|
|
.\" As far as I am concerned, the code I have written for this software
|
|
.\" can be used freely for any purpose. Any derived versions of this
|
|
.\" software must be clearly marked as such, and if the derived work is
|
|
.\" incompatible with the protocol description in the RFC file, it must be
|
|
.\" called by a name other than "ssh" or "Secure Shell".
|
|
.\"
|
|
.\"
|
|
.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
|
|
.\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
|
|
.\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd June 12 2008
|
|
.Dt SSH-KEYGEN 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ssh-keygen
|
|
.Nd authentication key generation, management and conversion
|
|
.Sh SYNOPSIS
|
|
.Nm ssh-keygen
|
|
.Bk -words
|
|
.Op Fl q
|
|
.Op Fl b Ar bits
|
|
.Fl t Ar type
|
|
.Op Fl N Ar new_passphrase
|
|
.Op Fl C Ar comment
|
|
.Op Fl f Ar output_keyfile
|
|
.Ek
|
|
.Nm ssh-keygen
|
|
.Fl p
|
|
.Op Fl P Ar old_passphrase
|
|
.Op Fl N Ar new_passphrase
|
|
.Op Fl f Ar keyfile
|
|
.Nm ssh-keygen
|
|
.Fl i
|
|
.Op Fl f Ar input_keyfile
|
|
.Nm ssh-keygen
|
|
.Fl e
|
|
.Op Fl f Ar input_keyfile
|
|
.Nm ssh-keygen
|
|
.Fl y
|
|
.Op Fl f Ar input_keyfile
|
|
.Nm ssh-keygen
|
|
.Fl c
|
|
.Op Fl P Ar passphrase
|
|
.Op Fl C Ar comment
|
|
.Op Fl f Ar keyfile
|
|
.Nm ssh-keygen
|
|
.Fl l
|
|
.Op Fl f Ar input_keyfile
|
|
.Nm ssh-keygen
|
|
.Fl B
|
|
.Op Fl f Ar input_keyfile
|
|
.Nm ssh-keygen
|
|
.Fl D Ar reader
|
|
.Nm ssh-keygen
|
|
.Fl F Ar hostname
|
|
.Op Fl f Ar known_hosts_file
|
|
.Nm ssh-keygen
|
|
.Fl H
|
|
.Op Fl f Ar known_hosts_file
|
|
.Nm ssh-keygen
|
|
.Fl R Ar hostname
|
|
.Op Fl f Ar known_hosts_file
|
|
.Nm ssh-keygen
|
|
.Fl U Ar reader
|
|
.Op Fl f Ar input_keyfile
|
|
.Nm ssh-keygen
|
|
.Fl r Ar hostname
|
|
.Op Fl f Ar input_keyfile
|
|
.Op Fl g
|
|
.Nm ssh-keygen
|
|
.Fl G Ar output_file
|
|
.Op Fl v
|
|
.Op Fl b Ar bits
|
|
.Op Fl M Ar memory
|
|
.Op Fl S Ar start_point
|
|
.Nm ssh-keygen
|
|
.Fl T Ar output_file
|
|
.Fl f Ar input_file
|
|
.Op Fl v
|
|
.Op Fl a Ar num_trials
|
|
.Op Fl W Ar generator
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
generates, manages and converts authentication keys for
|
|
.Xr ssh 1 .
|
|
.Nm
|
|
can create RSA keys for use by SSH protocol version 1 and RSA or DSA
|
|
keys for use by SSH protocol version 2.
|
|
The type of key to be generated is specified with the
|
|
.Fl t
|
|
option.
|
|
If invoked without any arguments,
|
|
.Nm
|
|
will generate an RSA key for use in SSH protocol 2 connections.
|
|
.Pp
|
|
.Nm
|
|
is also used to generate groups for use in Diffie-Hellman group
|
|
exchange (DH-GEX).
|
|
See the
|
|
.Sx MODULI GENERATION
|
|
section for details.
|
|
.Pp
|
|
Normally each user wishing to use SSH
|
|
with RSA or DSA authentication runs this once to create the authentication
|
|
key in
|
|
.Pa ~/.ssh/identity ,
|
|
.Pa ~/.ssh/id_dsa
|
|
or
|
|
.Pa ~/.ssh/id_rsa .
|
|
Additionally, the system administrator may use this to generate host keys,
|
|
as seen in
|
|
.Pa /etc/rc .
|
|
.Pp
|
|
Normally this program generates the key and asks for a file in which
|
|
to store the private key.
|
|
The public key is stored in a file with the same name but
|
|
.Dq .pub
|
|
appended.
|
|
The program also asks for a passphrase.
|
|
The passphrase may be empty to indicate no passphrase
|
|
(host keys must have an empty passphrase), or it may be a string of
|
|
arbitrary length.
|
|
A passphrase is similar to a password, except it can be a phrase with a
|
|
series of words, punctuation, numbers, whitespace, or any string of
|
|
characters you want.
|
|
Good passphrases are 10-30 characters long, are
|
|
not simple sentences or otherwise easily guessable (English
|
|
prose has only 1-2 bits of entropy per character, and provides very bad
|
|
passphrases), and contain a mix of upper and lowercase letters,
|
|
numbers, and non-alphanumeric characters.
|
|
The passphrase can be changed later by using the
|
|
.Fl p
|
|
option.
|
|
.Pp
|
|
There is no way to recover a lost passphrase.
|
|
If the passphrase is
|
|
lost or forgotten, a new key must be generated and copied to the
|
|
corresponding public key to other machines.
|
|
.Pp
|
|
For RSA1 keys,
|
|
there is also a comment field in the key file that is only for
|
|
convenience to the user to help identify the key.
|
|
The comment can tell what the key is for, or whatever is useful.
|
|
The comment is initialized to
|
|
.Dq user@host
|
|
when the key is created, but can be changed using the
|
|
.Fl c
|
|
option.
|
|
.Pp
|
|
After a key is generated, instructions below detail where the keys
|
|
should be placed to be activated.
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Fl a Ar trials
|
|
Specifies the number of primality tests to perform when screening DH-GEX
|
|
candidates using the
|
|
.Fl T
|
|
command.
|
|
.It Fl B
|
|
Show the bubblebabble digest of specified private or public key file.
|
|
.It Fl b Ar bits
|
|
Specifies the number of bits in the key to create.
|
|
For RSA keys, the minimum size is 768 bits and the default is 2048 bits.
|
|
Generally, 2048 bits is considered sufficient.
|
|
DSA keys must be exactly 1024 bits as specified by FIPS 186-2.
|
|
.It Fl C Ar comment
|
|
Provides a new comment.
|
|
.It Fl c
|
|
Requests changing the comment in the private and public key files.
|
|
This operation is only supported for RSA1 keys.
|
|
The program will prompt for the file containing the private keys, for
|
|
the passphrase if the key has one, and for the new comment.
|
|
.It Fl D Ar reader
|
|
Download the RSA public key stored in the smartcard in
|
|
.Ar reader .
|
|
.It Fl e
|
|
This option will read a private or public OpenSSH key file and
|
|
print the key in
|
|
RFC 4716 SSH Public Key File Format
|
|
to stdout.
|
|
This option allows exporting keys for use by several commercial
|
|
SSH implementations.
|
|
.It Fl F Ar hostname
|
|
Search for the specified
|
|
.Ar hostname
|
|
in a
|
|
.Pa known_hosts
|
|
file, listing any occurrences found.
|
|
This option is useful to find hashed host names or addresses and may also be
|
|
used in conjunction with the
|
|
.Fl H
|
|
option to print found keys in a hashed format.
|
|
.It Fl f Ar filename
|
|
Specifies the filename of the key file.
|
|
.It Fl G Ar output_file
|
|
Generate candidate primes for DH-GEX.
|
|
These primes must be screened for
|
|
safety (using the
|
|
.Fl T
|
|
option) before use.
|
|
.It Fl g
|
|
Use generic DNS format when printing fingerprint resource records using the
|
|
.Fl r
|
|
command.
|
|
.It Fl H
|
|
Hash a
|
|
.Pa known_hosts
|
|
file.
|
|
This replaces all hostnames and addresses with hashed representations
|
|
within the specified file; the original content is moved to a file with
|
|
a .old suffix.
|
|
These hashes may be used normally by
|
|
.Nm ssh
|
|
and
|
|
.Nm sshd ,
|
|
but they do not reveal identifying information should the file's contents
|
|
be disclosed.
|
|
This option will not modify existing hashed hostnames and is therefore safe
|
|
to use on files that mix hashed and non-hashed names.
|
|
.It Fl i
|
|
This option will read an unencrypted private (or public) key file
|
|
in SSH2-compatible format and print an OpenSSH compatible private
|
|
(or public) key to stdout.
|
|
.Nm
|
|
also reads the
|
|
RFC 4716 SSH Public Key File Format.
|
|
This option allows importing keys from several commercial
|
|
SSH implementations.
|
|
.It Fl l
|
|
Show fingerprint of specified public key file.
|
|
Private RSA1 keys are also supported.
|
|
For RSA and DSA keys
|
|
.Nm
|
|
tries to find the matching public key file and prints its fingerprint.
|
|
If combined with
|
|
.Fl v ,
|
|
an ASCII art representation of the key is supplied with the fingerprint.
|
|
.It Fl M Ar memory
|
|
Specify the amount of memory to use (in megabytes) when generating
|
|
candidate moduli for DH-GEX.
|
|
.It Fl N Ar new_passphrase
|
|
Provides the new passphrase.
|
|
.It Fl P Ar passphrase
|
|
Provides the (old) passphrase.
|
|
.It Fl p
|
|
Requests changing the passphrase of a private key file instead of
|
|
creating a new private key.
|
|
The program will prompt for the file
|
|
containing the private key, for the old passphrase, and twice for the
|
|
new passphrase.
|
|
.It Fl q
|
|
Silence
|
|
.Nm ssh-keygen .
|
|
Used by
|
|
.Pa /etc/rc
|
|
when creating a new key.
|
|
.It Fl R Ar hostname
|
|
Removes all keys belonging to
|
|
.Ar hostname
|
|
from a
|
|
.Pa known_hosts
|
|
file.
|
|
This option is useful to delete hashed hosts (see the
|
|
.Fl H
|
|
option above).
|
|
.It Fl r Ar hostname
|
|
Print the SSHFP fingerprint resource record named
|
|
.Ar hostname
|
|
for the specified public key file.
|
|
.It Fl S Ar start
|
|
Specify start point (in hex) when generating candidate moduli for DH-GEX.
|
|
.It Fl T Ar output_file
|
|
Test DH group exchange candidate primes (generated using the
|
|
.Fl G
|
|
option) for safety.
|
|
.It Fl t Ar type
|
|
Specifies the type of key to create.
|
|
The possible values are
|
|
.Dq rsa1
|
|
for protocol version 1 and
|
|
.Dq rsa
|
|
or
|
|
.Dq dsa
|
|
for protocol version 2.
|
|
.It Fl U Ar reader
|
|
Upload an existing RSA private key into the smartcard in
|
|
.Ar reader .
|
|
.It Fl v
|
|
Verbose mode.
|
|
Causes
|
|
.Nm
|
|
to print debugging messages about its progress.
|
|
This is helpful for debugging moduli generation.
|
|
Multiple
|
|
.Fl v
|
|
options increase the verbosity.
|
|
The maximum is 3.
|
|
.It Fl W Ar generator
|
|
Specify desired generator when testing candidate moduli for DH-GEX.
|
|
.It Fl y
|
|
This option will read a private
|
|
OpenSSH format file and print an OpenSSH public key to stdout.
|
|
.El
|
|
.Sh MODULI GENERATION
|
|
.Nm
|
|
may be used to generate groups for the Diffie-Hellman Group Exchange
|
|
(DH-GEX) protocol.
|
|
Generating these groups is a two-step process: first, candidate
|
|
primes are generated using a fast, but memory intensive process.
|
|
These candidate primes are then tested for suitability (a CPU-intensive
|
|
process).
|
|
.Pp
|
|
Generation of primes is performed using the
|
|
.Fl G
|
|
option.
|
|
The desired length of the primes may be specified by the
|
|
.Fl b
|
|
option.
|
|
For example:
|
|
.Pp
|
|
.Dl # ssh-keygen -G moduli-2048.candidates -b 2048
|
|
.Pp
|
|
By default, the search for primes begins at a random point in the
|
|
desired length range.
|
|
This may be overridden using the
|
|
.Fl S
|
|
option, which specifies a different start point (in hex).
|
|
.Pp
|
|
Once a set of candidates have been generated, they must be tested for
|
|
suitability.
|
|
This may be performed using the
|
|
.Fl T
|
|
option.
|
|
In this mode
|
|
.Nm
|
|
will read candidates from standard input (or a file specified using the
|
|
.Fl f
|
|
option).
|
|
For example:
|
|
.Pp
|
|
.Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
|
|
.Pp
|
|
By default, each candidate will be subjected to 100 primality tests.
|
|
This may be overridden using the
|
|
.Fl a
|
|
option.
|
|
The DH generator value will be chosen automatically for the
|
|
prime under consideration.
|
|
If a specific generator is desired, it may be requested using the
|
|
.Fl W
|
|
option.
|
|
Valid generator values are 2, 3, and 5.
|
|
.Pp
|
|
Screened DH groups may be installed in
|
|
.Pa /etc/moduli .
|
|
It is important that this file contains moduli of a range of bit lengths and
|
|
that both ends of a connection share common moduli.
|
|
.Sh FILES
|
|
.Bl -tag -width Ds
|
|
.It Pa ~/.ssh/identity
|
|
Contains the protocol version 1 RSA authentication identity of the user.
|
|
This file should not be readable by anyone but the user.
|
|
It is possible to
|
|
specify a passphrase when generating the key; that passphrase will be
|
|
used to encrypt the private part of this file using 3DES.
|
|
This file is not automatically accessed by
|
|
.Nm
|
|
but it is offered as the default file for the private key.
|
|
.Xr ssh 1
|
|
will read this file when a login attempt is made.
|
|
.It Pa ~/.ssh/identity.pub
|
|
Contains the protocol version 1 RSA public key for authentication.
|
|
The contents of this file should be added to
|
|
.Pa ~/.ssh/authorized_keys
|
|
on all machines
|
|
where the user wishes to log in using RSA authentication.
|
|
There is no need to keep the contents of this file secret.
|
|
.It Pa ~/.ssh/id_dsa
|
|
Contains the protocol version 2 DSA authentication identity of the user.
|
|
This file should not be readable by anyone but the user.
|
|
It is possible to
|
|
specify a passphrase when generating the key; that passphrase will be
|
|
used to encrypt the private part of this file using 3DES.
|
|
This file is not automatically accessed by
|
|
.Nm
|
|
but it is offered as the default file for the private key.
|
|
.Xr ssh 1
|
|
will read this file when a login attempt is made.
|
|
.It Pa ~/.ssh/id_dsa.pub
|
|
Contains the protocol version 2 DSA public key for authentication.
|
|
The contents of this file should be added to
|
|
.Pa ~/.ssh/authorized_keys
|
|
on all machines
|
|
where the user wishes to log in using public key authentication.
|
|
There is no need to keep the contents of this file secret.
|
|
.It Pa ~/.ssh/id_rsa
|
|
Contains the protocol version 2 RSA authentication identity of the user.
|
|
This file should not be readable by anyone but the user.
|
|
It is possible to
|
|
specify a passphrase when generating the key; that passphrase will be
|
|
used to encrypt the private part of this file using 3DES.
|
|
This file is not automatically accessed by
|
|
.Nm
|
|
but it is offered as the default file for the private key.
|
|
.Xr ssh 1
|
|
will read this file when a login attempt is made.
|
|
.It Pa ~/.ssh/id_rsa.pub
|
|
Contains the protocol version 2 RSA public key for authentication.
|
|
The contents of this file should be added to
|
|
.Pa ~/.ssh/authorized_keys
|
|
on all machines
|
|
where the user wishes to log in using public key authentication.
|
|
There is no need to keep the contents of this file secret.
|
|
.It Pa /etc/moduli
|
|
Contains Diffie-Hellman groups used for DH-GEX.
|
|
The file format is described in
|
|
.Xr moduli 5 .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr ssh 1 ,
|
|
.Xr ssh-add 1 ,
|
|
.Xr ssh-agent 1 ,
|
|
.Xr moduli 5 ,
|
|
.Xr sshd 8
|
|
.Rs
|
|
.%R RFC 4716
|
|
.%T "The Secure Shell (SSH) Public Key File Format"
|
|
.%D 2006
|
|
.Re
|
|
.Sh AUTHORS
|
|
OpenSSH is a derivative of the original and free
|
|
ssh 1.2.12 release by Tatu Ylonen.
|
|
Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
|
|
Theo de Raadt and Dug Song
|
|
removed many bugs, re-added newer features and
|
|
created OpenSSH.
|
|
Markus Friedl contributed the support for SSH
|
|
protocol versions 1.5 and 2.0.
|