rewrite moduli(5). The old one contained quite a bit of historical and

irrelevant information. It also included an advertising clause in
its license which dtucker tried unsuccessfully to have rescinded, and we
want OpenSSH and its related documentation to be as free as possible.

feedback & ok deraadt@

1 files changed, 100 insertions, 133 deletions

diff --git a/share/man/man5/moduli.5 b/share/man/man5/moduli.5
index 94f1a7d8f29..4a99439cc64 100644
--- a/share/man/man5/moduli.5
+++ b/share/man/man5/moduli.5
@@ -1,157 +1,124 @@
-.\" $OpenBSD: moduli.5,v 1.11 2007/05/31 19:19:58 jmc Exp $
+.\"	$OpenBSD: moduli.5,v 1.12 2008/06/26 05:57:54 djm 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.
-.\"
-.\" Manual page, using -mandoc macros
-.\"
-.Dd $Mdocdate: May 31 2007 $
+.\" 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.
+.Dd $Mdocdate: June 26 2008 $
 .Dt MODULI 5
 .Os
 .Sh NAME
 .Nm moduli
-.Nd system moduli file
+.Nd Diffie Hellman moduli
 .Sh DESCRIPTION
 The
 .Pa /etc/moduli
-file contains the system-wide Diffie-Hellman prime moduli for
-.Xr sshd 8 .
+file contains prime numbers and generators for use by 
+.Xr sshd 8
+in the Diffie-Hellman Group Exchange key exchange method.
 .Pp
-Each line in this file contains the following fields:
-Time, Type, Tests, Tries, Size, Generator, Modulus.
-The fields are separated by white space (tab or blank).
+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
-.Fa Time : 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.
+The file consists of newline-separated records, one per modulus,
+containing seven space separated fields.
+These fields are as follows:
 .Pp
-.Fa Type : decimal .
-Specifies the internal structure of the prime modulus.
+.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 -offset 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-Germain (q = (p-1)/2);
-usually generated in the process of testing safe or strong primes.
-.It 5 :
-strong;
-useful for RSA public key generation.
+.Bl -tag -width 0x00 -compact
+.It 0
+Unknown, not tested
+.It 2
+"Safe" prime; (p-1)/2 is also prime.
+.It 4
+Sophie Germain; (p+1)*2 is also prime.
 .El
 .Pp
-.Fa Tests : decimal (bit field) .
-Specifies the methods used in checking for primality.
-Usually, more than one test is used.
+Moduli candidates initially produced by
+.Xr ssh-keygen 1
+are Sophie Germain primes (type 4).
+Futher 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 indent -offset indent -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.
-.It 2 :
-sieve;
-checked for division by a range of smaller primes.
-.It 4 :
-Miller-Rabin.
-.It 8 :
-Jacobi.
-.It 16 :
-Elliptic Curve.
+.Bl -tag -width 0x00 -compact
+.It 0x00
+Not tested
+.It 0x01
+Composite number - not prime.
+.It 0x02
+Sieve of Eratosthenes
+.It 0x04
+Probabalistic Miller-Rabin primality tests.
 .El
 .Pp
-.Fa Tries : decimal .
-Depends on the value of the highest valid Test bit,
-where the method specified is:
-.Pp
-.Bl -tag -width indent -offset 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).
+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 of primaility 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
-.Fa Size : decimal .
-Specifies the number of the most significant bit (0 to M).
-.Pp
-.Fa Generator : hex string .
-Specifies the best generator for a Diffie-Hellman exchange.
-0 = unknown or variable,
-2, 3, 5, etc.
-.Pp
-.Fa Modulus : hex string .
-The prime modulus.
-.Pp
-The file is searched for moduli that meet the appropriate
-Time, Size and Generator criteria.
-When more than one meet the criteria,
-the selection should be weighted toward newer moduli,
-without completely disqualifying older moduli.
+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/moduli
+that best meets the size requirement.
 .Pp
-New moduli may be generated using the
-.Xr ssh-keygen 1
-tool.
-.Sh FILES
-.Bl -tag -width /etc/moduli -compact
-.It Pa /etc/moduli
-.El
 .Sh SEE ALSO
 .Xr ssh-keygen 1 ,
-.Xr sshd 8
+.Xr sshd 8 ,
+.Rs
+.%R RFC 4419
+.%T "Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol"
+.%D 2006
+.Re