1 files changed, 138 insertions, 116 deletions

diff --git a/ssh-keygen.0 b/ssh-keygen.0
index aed4a14ad..fb7838724 100644
--- a/ssh-keygen.0
+++ b/ssh-keygen.0
@@ -7,8 +7,8 @@ SYNOPSIS
      ssh-keygen [-q] [-b bits] -t type [-N new_passphrase] [-C comment]
                 [-f output_keyfile]
      ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile]
-     ssh-keygen -i [-f input_keyfile]
-     ssh-keygen -e [-f input_keyfile]
+     ssh-keygen -i [-m key_format] [-f input_keyfile]
+     ssh-keygen -e [-m key_format] [-f input_keyfile]
      ssh-keygen -y [-f input_keyfile]
      ssh-keygen -c [-P passphrase] [-C comment] [-f keyfile]
      ssh-keygen -l [-f input_keyfile]
@@ -22,7 +22,7 @@ SYNOPSIS
      ssh-keygen -T output_file -f input_file [-v] [-a num_trials]
                 [-W generator]
      ssh-keygen -s ca_key -I certificate_identity [-h] [-n principals]
-                [-O constraint] [-V validity_interval] file ...
+                [-O option] [-V validity_interval] [-z serial_number] file ...
      ssh-keygen -L [-f input_keyfile]
 
 DESCRIPTION
@@ -46,14 +46,14 @@ DESCRIPTION
      name but ``.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 se-
-     ries of words, punctuation, numbers, whitespace, or any string of charac-
-     ters you want.  Good passphrases are 10-30 characters long, are not sim-
-     ple 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-alphanu-
-     meric characters.  The passphrase can be changed later by using the -p
-     option.
+     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 -p option.
 
      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
@@ -61,9 +61,9 @@ DESCRIPTION
 
      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 initial-
-     ized to ``user@host'' when the key is created, but can be changed using
-     the -c option.
+     tell what the key is for, or whatever is useful.  The comment is
+     initialized to ``user@host'' when the key is created, but can be changed
+     using the -c option.
 
      After a key is generated, instructions below detail where the keys should
      be placed to be activated.
@@ -79,26 +79,29 @@ DESCRIPTION
 
      -b 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.  Gen-
-             erally, 2048 bits is considered sufficient.  DSA keys must be ex-
-             actly 1024 bits as specified by FIPS 186-2.
+             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.
 
      -C comment
              Provides a new comment.
 
      -c      Requests changing the comment in the private and public key
-             files.  This operation is only supported for RSA1 keys.  The pro-
-             gram will prompt for the file containing the private keys, for
+             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.
 
      -D pkcs11
-             Download the RSA public keys provided by the PKCS#11 shared li-
-             brary pkcs11.
+             Download the RSA public keys provided by the PKCS#11 shared
+             library pkcs11.  When used in combination with -s, this option
+             indicates that a CA key resides in a PKCS#11 token (see the
+             CERTIFICATES section for details).
 
      -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.
+             print to stdout the key in one of the formats specified by the -m
+             option.  The default export format is ``RFC4716''.  This option
+             allows exporting OpenSSH keys for use by other programs,
+             including several commercial SSH implementations.
 
      -F hostname
              Search for the specified hostname in a known_hosts file, listing
@@ -116,8 +119,8 @@ DESCRIPTION
      -g      Use generic DNS format when printing fingerprint resource records
              using the -r command.
 
-     -H      Hash a known_hosts file.  This replaces all hostnames and ad-
-             dresses with hashed representations within the specified file;
+     -H      Hash a 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 ssh and sshd, but they do
              not reveal identifying information should the file's contents be
@@ -133,41 +136,48 @@ DESCRIPTION
              the CERTIFICATES section for details.
 
      -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.  ssh-keygen also reads the RFC 4716
-             SSH Public Key File Format.  This option allows importing keys
-             from several commercial SSH implementations.
+             in the format specified by the -m option and print an OpenSSH
+             compatible private (or public) key to stdout.  This option allows
+             importing keys from other software, including several commercial
+             SSH implementations.  The default import format is ``RFC4716''.
 
      -L      Prints the contents of a certificate.
 
      -l      Show fingerprint of specified public key file.  Private RSA1 keys
              are also supported.  For RSA and DSA keys ssh-keygen tries to
              find the matching public key file and prints its fingerprint.  If
-             combined with -v, an ASCII art representation of the key is sup-
-             plied with the fingerprint.
+             combined with -v, an ASCII art representation of the key is
+             supplied with the fingerprint.
 
      -M memory
-             Specify the amount of memory to use (in megabytes) when generat-
-             ing candidate moduli for DH-GEX.
+             Specify the amount of memory to use (in megabytes) when
+             generating candidate moduli for DH-GEX.
+
+     -m key_format
+             Specify a key format for the -i (import) or -e (export)
+             conversion options.  The supported key formats are: ``RFC4716''
+             (RFC 4716/SSH2 public or private key), ``PKCS8'' (PEM PKCS8
+             public key) or ``PEM'' (PEM public key).  The default conversion
+             format is ``RFC4716''.
 
      -N new_passphrase
              Provides the new passphrase.
 
      -n principals
-             Specify one or more principals (user or host names) to be includ-
-             ed in a certificate when signing a key.  Multiple principals may
-             be specified, separated by commas.  Please see the CERTIFICATES
-             section for details.
+             Specify one or more principals (user or host names) to be
+             included in a certificate when signing a key.  Multiple
+             principals may be specified, separated by commas.  Please see the
+             CERTIFICATES section for details.
 
-     -O constraint
-             Specify a certificate constraint when signing a key.  This option
-             may be specified multiple times.  Please see the CERTIFICATES
-             section for details.  The constraints that are valid for user
-             certificates are:
+     -O option
+             Specify a certificate option when signing a key.  This option may
+             be specified multiple times.  Please see the CERTIFICATES section
+             for details.  The options that are valid for user certificates
+             are:
 
-             clear   Clear all enabled permissions.  This is useful for clear-
-                     ing the default set of permissions so permissions may be
-                     added individually.
+             clear   Clear all enabled permissions.  This is useful for
+                     clearing the default set of permissions so permissions
+                     may be added individually.
 
              force-command=command
                      Forces the execution of command instead of any shell or
@@ -206,11 +216,11 @@ DESCRIPTION
 
              source-address=address_list
                      Restrict the source addresses from which the certificate
-                     is considered valid.  The address_list is a comma-sepa-
-                     rated list of one or more address/netmask pairs in CIDR
-                     format.
+                     is considered valid.  The address_list is a comma-
+                     separated list of one or more address/netmask pairs in
+                     CIDR format.
 
-             At present, no constraints are valid for host keys.
+             At present, no options are valid for host keys.
 
      -P passphrase
              Provides the (old) passphrase.
@@ -245,21 +255,21 @@ DESCRIPTION
 
      -t type
              Specifies the type of key to create.  The possible values are
-             ``rsa1'' for protocol version 1 and ``rsa'' or ``dsa'' for proto-
-             col version 2.
+             ``rsa1'' for protocol version 1 and ``rsa'' or ``dsa'' for
+             protocol version 2.
 
      -V validity_interval
-             Specify a validity interval when signing a certificate.  A valid-
-             ity interval may consist of a single time, indicating that the
-             certificate is valid beginning now and expiring at that time, or
-             may consist of two times separated by a colon to indicate an ex-
-             plicit time interval.  The start time may be specified as a date
-             in YYYYMMDD format, a time in YYYYMMDDHHMMSS format or a relative
-             time (to the current time) consisting of a minus sign followed by
-             a relative time in the format described in the TIME FORMATS sec-
-             tion of sshd_config(5).  The end time may be specified as a
-             YYYYMMDD date, a YYYYMMDDHHMMSS time or a relative time starting
-             with a plus character.
+             Specify a validity interval when signing a certificate.  A
+             validity interval may consist of a single time, indicating that
+             the certificate is valid beginning now and expiring at that time,
+             or may consist of two times separated by a colon to indicate an
+             explicit time interval.  The start time may be specified as a
+             date in YYYYMMDD format, a time in YYYYMMDDHHMMSS format or a
+             relative time (to the current time) consisting of a minus sign
+             followed by a relative time in the format described in the TIME
+             FORMATS section of sshd_config(5).  The end time may be specified
+             as a YYYYMMDD date, a YYYYMMDDHHMMSS time or a relative time
+             starting with a plus character.
 
              For example: ``+52w1d'' (valid from now to 52 weeks and one day
              from now), ``-4w:+4w'' (valid from four weeks ago to four weeks
@@ -269,9 +279,9 @@ DESCRIPTION
              2011).
 
      -v      Verbose mode.  Causes ssh-keygen to print debugging messages
-             about its progress.  This is helpful for debugging moduli genera-
-             tion.  Multiple -v options increase the verbosity.  The maximum
-             is 3.
+             about its progress.  This is helpful for debugging moduli
+             generation.  Multiple -v options increase the verbosity.  The
+             maximum is 3.
 
      -W generator
              Specify desired generator when testing candidate moduli for DH-
@@ -280,12 +290,17 @@ DESCRIPTION
      -y      This option will read a private OpenSSH format file and print an
              OpenSSH public key to stdout.
 
+     -z serial_number
+             Specifies a serial number to be embedded in the certificate to
+             distinguish this certificate from others from the same CA.  The
+             default serial number is zero.
+
 MODULI GENERATION
      ssh-keygen may be used to generate groups for the Diffie-Hellman Group
-     Exchange (DH-GEX) protocol.  Generating these groups is a two-step pro-
-     cess: first, candidate primes are generated using a fast, but memory in-
-     tensive process.  These candidate primes are then tested for suitability
-     (a CPU-intensive process).
+     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).
 
      Generation of primes is performed using the -G option.  The desired
      length of the primes may be specified by the -b option.  For example:
@@ -293,8 +308,8 @@ MODULI GENERATION
            # ssh-keygen -G moduli-2048.candidates -b 2048
 
      By default, the search for primes begins at a random point in the desired
-     length range.  This may be overridden using the -S option, which speci-
-     fies a different start point (in hex).
+     length range.  This may be overridden using the -S option, which
+     specifies a different start point (in hex).
 
      Once a set of candidates have been generated, they must be tested for
      suitability.  This may be performed using the -T option.  In this mode
@@ -317,15 +332,15 @@ CERTIFICATES
      ssh-keygen supports signing of keys to produce certificates that may be
      used for user or host authentication.  Certificates consist of a public
      key, some identity information, zero or more principal (user or host)
-     names and an optional set of constraints that are signed by a Certifica-
-     tion Authority (CA) key.  Clients or servers may then trust only the CA
-     key and verify its signature on a certificate rather than trusting many
-     user/host keys.  Note that OpenSSH certificates are a different, and much
-     simpler, format to the X.509 certificates used in ssl(8).
+     names and a set of options that are signed by a Certification Authority
+     (CA) key.  Clients or servers may then trust only the CA key and verify
+     its signature on a certificate rather than trusting many user/host keys.
+     Note that OpenSSH certificates are a different, and much simpler, format
+     to the X.509 certificates used in ssl(8).
 
-     ssh-keygen supports two types of certificates: user and host.  User cer-
-     tificates authenticate users to servers, whereas host certificates au-
-     thenticate server hosts to users.  To generate a user certificate:
+     ssh-keygen supports two types of certificates: user and host.  User
+     certificates authenticate users to servers, whereas host certificates
+     authenticate server hosts to users.  To generate a user certificate:
 
            $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
 
@@ -334,83 +349,90 @@ CERTIFICATES
 
            $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
 
-     The host certificate will be output to /path/to/host_key-cert.pub.  In
-     both cases, key_id is a "key identifier" that is logged by the server
+     The host certificate will be output to /path/to/host_key-cert.pub.
+
+     It is possible to sign using a CA key stored in a PKCS#11 token by
+     providing the token library using -D and identifying the CA key by
+     providing its public half as an argument to -s:
+
+           $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub
+
+     In all cases, key_id is a "key identifier" that is logged by the server
      when the certificate is used for authentication.
 
-     Certificates may be limited to be valid for a set of principal (us-
-     er/host) names.  By default, generated certificates are valid for all
-     users or hosts.  To generate a certificate for a specified set of princi-
-     pals:
+     Certificates may be limited to be valid for a set of principal
+     (user/host) names.  By default, generated certificates are valid for all
+     users or hosts.  To generate a certificate for a specified set of
+     principals:
 
            $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
            $ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub
 
      Additional limitations on the validity and use of user certificates may
-     be specified through certificate constraints.  A constrained certificate
-     may disable features of the SSH session, may be valid only when presented
-     from particular source addresses or may force the use of a specific com-
-     mand.  For a list of valid certificate constraints, see the documentation
+     be specified through certificate options.  A certificate option may
+     disable features of the SSH session, may be valid only when presented
+     from particular source addresses or may force the use of a specific
+     command.  For a list of valid certificate options, see the documentation
      for the -O option above.
 
      Finally, certificates may be defined with a validity lifetime.  The -V
-     option allows specification of certificate start and end times.  A cer-
-     tificate that is presented at a time outside this range will not be con-
-     sidered valid.  By default, certificates have a maximum validity inter-
-     val.
+     option allows specification of certificate start and end times.  A
+     certificate that is presented at a time outside this range will not be
+     considered valid.  By default, certificates have a maximum validity
+     interval.
 
-     For certificates to be used for user or host authentication, the CA pub-
-     lic key must be trusted by sshd(8) or ssh(1).  Please refer to those man-
-     ual pages for details.
+     For certificates to be used for user or host authentication, the CA
+     public key must be trusted by sshd(8) or ssh(1).  Please refer to those
+     manual pages for details.
 
 FILES
      ~/.ssh/identity
              Contains the protocol version 1 RSA authentication identity of
-             the user.  This file should not be readable by anyone but the us-
-             er.  It is possible to specify a passphrase when generating the
+             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 128-bit AES.  This file is not automatically ac-
-             cessed by ssh-keygen but it is offered as the default file for
+             this file using 128-bit AES.  This file is not automatically
+             accessed by ssh-keygen but it is offered as the default file for
              the private key.  ssh(1) will read this file when a login attempt
              is made.
 
      ~/.ssh/identity.pub
-             Contains the protocol version 1 RSA public key for authentica-
-             tion.  The contents of this file should be added to
+             Contains the protocol version 1 RSA public key for
+             authentication.  The contents of this file should be added to
              ~/.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.
 
      ~/.ssh/id_dsa
              Contains the protocol version 2 DSA authentication identity of
-             the user.  This file should not be readable by anyone but the us-
-             er.  It is possible to specify a passphrase when generating the
+             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 128-bit AES.  This file is not automatically ac-
-             cessed by ssh-keygen but it is offered as the default file for
+             this file using 128-bit AES.  This file is not automatically
+             accessed by ssh-keygen but it is offered as the default file for
              the private key.  ssh(1) will read this file when a login attempt
              is made.
 
      ~/.ssh/id_dsa.pub
-             Contains the protocol version 2 DSA public key for authentica-
-             tion.  The contents of this file should be added to
+             Contains the protocol version 2 DSA public key for
+             authentication.  The contents of this file should be added to
              ~/.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.
 
      ~/.ssh/id_rsa
              Contains the protocol version 2 RSA authentication identity of
-             the user.  This file should not be readable by anyone but the us-
-             er.  It is possible to specify a passphrase when generating the
+             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 128-bit AES.  This file is not automatically ac-
-             cessed by ssh-keygen but it is offered as the default file for
+             this file using 128-bit AES.  This file is not automatically
+             accessed by ssh-keygen but it is offered as the default file for
              the private key.  ssh(1) will read this file when a login attempt
              is made.
 
      ~/.ssh/id_rsa.pub
-             Contains the protocol version 2 RSA public key for authentica-
-             tion.  The contents of this file should be added to
+             Contains the protocol version 2 RSA public key for
+             authentication.  The contents of this file should be added to
              ~/.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.
@@ -431,4 +453,4 @@ AUTHORS
      created OpenSSH.  Markus Friedl contributed the support for SSH protocol
      versions 1.5 and 2.0.
 
-OpenBSD 4.7                     March 13, 2010                               7
+OpenBSD 4.8                     August 4, 2010                     OpenBSD 4.8