Skip site navigation (1)Skip section navigation (2)
Date:      Fri, 20 Jul 2012 01:11:53 +0000 (UTC)
From:      Xin LI <delphij@FreeBSD.org>
To:        src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org
Subject:   svn commit: r238631 - head/share/man/man5
Message-ID:  <201207200111.q6K1Brc2040755@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: delphij
Date: Fri Jul 20 01:11:53 2012
New Revision: 238631
URL: http://svn.freebsd.org/changeset/base/238631

Log:
  Import an updated version of moduli(5) manual page from OpenBSD.
  
  MFC after:	1 month

Modified:
  head/share/man/man5/moduli.5

Modified: head/share/man/man5/moduli.5
==============================================================================
--- head/share/man/man5/moduli.5	Fri Jul 20 00:47:23 2012	(r238630)
+++ head/share/man/man5/moduli.5	Fri Jul 20 01:11:53 2012	(r238631)
@@ -1,159 +1,125 @@
-.\" $OpenBSD: moduli.5,v 1.3 2001/06/24 18:50:52 provos Exp $
+.\"	$OpenBSD: moduli.5,v 1.16 2011/11/28 08:46:27 eric Exp $
 .\"
-.\" Copyright 1997, 2000 William Allen Simpson <wsimpson@greendragon.com>
-.\" All rights reserved.
+.\" Copyright (c) 2008 Damien Miller <djm@mindrot.org>
 .\"
-.\" 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.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"      This product includes software designed by William Allen Simpson.
-.\" 4. The name of the author may not be used to endorse or promote products
-.\"    derived from this software without specific prior written permission.
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
 .\"
-.\" 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.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 28, 1997
+.Dd July 19, 2012
 .Dt MODULI 5
 .Os
 .Sh NAME
 .Nm moduli
-.Nd system moduli file
+.Nd Diffie-Hellman moduli
 .Sh DESCRIPTION
 The
-.Nm
-file contains the system-wide Diffie-Hellman prime moduli for the
-.Xr photurisd 8
-and
+.Pa /etc/ssh/moduli
+file contains prime numbers and generators for use by
 .Xr sshd 8
-programs.
+in the Diffie-Hellman Group Exchange key exchange method.
 .Pp
-Each line in this file contains the following fields:
-.Va Time , Type , Tests , Tries , Size , Generator ,
-and
-.Va Modulus .
-The fields are separated by white space (tab or blank).
-.Bl -tag -width indent
-.It Va Time Pq Vt yyyymmddhhmmss
-Specifies the system time that the line was appended to the file.
-The value 00000000000000 means unknown (historic).
-.\"The file is sorted in ascending order.
-.It Va Type Pq Vt decimal
-Specifies the internal structure of the prime modulus.
+New moduli may be generated with
+.Xr ssh-keygen 1
+using a two-step process.
+An initial
+.Em candidate generation
+pass, using
+.Ic ssh-keygen -G ,
+calculates numbers that are likely to be useful.
+A second
+.Em primality testing
+pass, using
+.Ic ssh-keygen -T ,
+provides a high degree of assurance that the numbers are prime and are
+safe for use in Diffie-Hellman operations by
+.Xr sshd 8 .
+This
+.Nm
+format is used as the output from each pass.
 .Pp
-.Bl -tag -width indent -compact
-.It 0
-unknown;
-often learned from peer during protocol operation,
-and saved for later analysis.
-.It 1
-unstructured;
-a common large number.
-.It 2
-safe (p = 2q + 1);
-meets basic structural requirements.
-.It 3
-Schnorr.
-.It 4
-Sophie-Germaine (q = (p-1)/2);
-usually generated in the process of testing safe or strong primes.
-.It 5
-strong;
-useful for RSA public key generation.
-.El
-.It Xo
-.Va Tests Pq Vt decimal
-(bit field)
-.Xc
-Specifies the methods used in checking for primality.
-Usually, more than one test is used.
+The file consists of newline-separated records, one per modulus,
+containing seven space-separated fields.
+These fields are as follows:
+.Bl -tag -width Description -offset indent
+.It timestamp
+The time that the modulus was last processed as YYYYMMDDHHMMSS.
+.It type
+Decimal number specifying the internal structure of the prime modulus.
+Supported types are:
 .Pp
-.Bl -tag -width indent -compact
+.Bl -tag -width 0x00 -compact
 .It 0
-not tested;
-often learned from peer during protocol operation,
-and saved for later analysis.
-.It 1
-composite;
-failed one or more tests.
-In this case, the highest bit specifies the test that failed.
+Unknown, not tested.
 .It 2
-sieve;
-checked for division by a range of smaller primes.
+"Safe" prime; (p-1)/2 is also prime.
 .It 4
-Miller-Rabin.
-.It 8
-Jacobi.
-.It 16
-Elliptic Curve.
+Sophie Germain; 2p+1 is also prime.
 .El
-.It Va Tries Pq Vt decimal
-Depends on the value of the highest valid Test bit,
-where the method specified is:
 .Pp
-.Bl -tag -width indent -compact
-.It 0
-not tested
-(always zero).
-.It 1
-composite
-(irrelevant).
-.It 2
-sieve;
-number of primes sieved.
-Commonly on the order of 32,000,000.
-.It 4
-Miller-Rabin;
-number of M-R iterations.
-Commonly on the order of 32 to 64.
-.It 8
-Jacobi;
-unknown
-(always zero).
-.It 16
-Elliptic Curve;
-unused
-(always zero).
-.El
-.It Va Size Pq Vt decimal
-Specifies the number of significant bits.
-.It Va Generator Pq Vt "hex string"
-Specifies the best generator for a Diffie-Hellman exchange.
-0 = unknown or variable,
-2, 3, 5, etc.
-.It Va Modulus Pq Vt "hex string"
-The prime modulus.
+Moduli candidates initially produced by
+.Xr ssh-keygen 1
+are Sophie Germain primes (type 4).
+Further primality testing with
+.Xr ssh-keygen 1
+produces safe prime moduli (type 2) that are ready for use in
+.Xr sshd 8 .
+Other types are not used by OpenSSH.
+.It tests
+Decimal number indicating the type of primality tests that the number
+has been subjected to represented as a bitmask of the following values:
+.Pp
+.Bl -tag -width 0x00 -compact
+.It 0x00
+Not tested.
+.It 0x01
+Composite number \(en not prime.
+.It 0x02
+Sieve of Eratosthenes.
+.It 0x04
+Probabilistic Miller-Rabin primality tests.
 .El
 .Pp
-The file is searched for moduli that meet the appropriate
-.Va Time , Size
-and
-.Va Generator
-criteria.
-When more than one meet the criteria,
-the selection should be weighted toward newer moduli,
-without completely disqualifying older moduli.
-.Sh FILES
-.Bl -tag -width ".Pa /etc/ssh/moduli" -compact
-.It Pa /etc/ssh/moduli
+The
+.Xr ssh-keygen 1
+moduli candidate generation uses the Sieve of Eratosthenes (flag 0x02).
+Subsequent
+.Xr ssh-keygen 1
+primality tests are Miller-Rabin tests (flag 0x04).
+.It trials
+Decimal number indicating the number of primality trials
+that have been performed on the modulus.
+.It size
+Decimal number indicating the size of the prime in bits.
+.It generator
+The recommended generator for use with this modulus (hexadecimal).
+.It modulus
+The modulus itself in hexadecimal.
 .El
+.Pp
+When performing Diffie-Hellman Group Exchange,
+.Xr sshd 8
+first estimates the size of the modulus required to produce enough
+Diffie-Hellman output to sufficiently key the selected symmetric cipher.
+.Xr sshd 8
+then randomly selects a modulus from
+.Fa /etc/ssh/moduli
+that best meets the size requirement.
 .Sh SEE ALSO
-.Xr photurisd 8 ,
+.Xr ssh-keygen 1 ,
 .Xr sshd 8
+.Rs
+.%R RFC 4419
+.%T "Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol"
+.%D 2006
+.Re



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201207200111.q6K1Brc2040755>