Date: Mon, 20 Aug 2012 18:33:24 +0000 (UTC) From: Xin LI <delphij@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-7@freebsd.org Subject: svn commit: r239463 - in stable: 7/share/man/man5 8/share/man/man5 9/share/man/man5 Message-ID: <201208201833.q7KIXOe3075952@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: delphij Date: Mon Aug 20 18:33:23 2012 New Revision: 239463 URL: http://svn.freebsd.org/changeset/base/239463 Log: MFC r238631: Import an updated version of moduli(5) manual page from OpenBSD. Modified: stable/7/share/man/man5/moduli.5 Directory Properties: stable/7/share/man/man5/ (props changed) Changes in other areas also in this revision: Modified: stable/8/share/man/man5/moduli.5 stable/9/share/man/man5/moduli.5 Directory Properties: stable/8/share/man/man5/ (props changed) stable/9/share/man/man5/ (props changed) Modified: stable/7/share/man/man5/moduli.5 ============================================================================== --- stable/7/share/man/man5/moduli.5 Mon Aug 20 18:33:03 2012 (r239462) +++ stable/7/share/man/man5/moduli.5 Mon Aug 20 18:33:23 2012 (r239463) @@ -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?201208201833.q7KIXOe3075952>