From owner-svn-src-all@FreeBSD.ORG Tue Aug 21 09:55:58 2012 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 55437106566C; Tue, 21 Aug 2012 09:55:58 +0000 (UTC) (envelope-from delphij@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 3E2B58FC15; Tue, 21 Aug 2012 09:55:58 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q7L9twQf010305; Tue, 21 Aug 2012 09:55:58 GMT (envelope-from delphij@svn.freebsd.org) Received: (from delphij@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id q7L9twIx010304; Tue, 21 Aug 2012 09:55:58 GMT (envelope-from delphij@svn.freebsd.org) Message-Id: <201208210955.q7L9twIx010304@svn.freebsd.org> From: Xin LI Date: Tue, 21 Aug 2012 09:55:58 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-releng@freebsd.org X-SVN-Group: releng MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r239489 - releng/9.1/share/man/man5 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 21 Aug 2012 09:55:58 -0000 Author: delphij Date: Tue Aug 21 09:55:57 2012 New Revision: 239489 URL: http://svn.freebsd.org/changeset/base/239489 Log: MFC r238631: Import an updated version of moduli(5) manual page from OpenBSD. Approved by: re (kib) Modified: releng/9.1/share/man/man5/moduli.5 Directory Properties: releng/9.1/share/man/man5/ (props changed) Modified: releng/9.1/share/man/man5/moduli.5 ============================================================================== --- releng/9.1/share/man/man5/moduli.5 Tue Aug 21 09:43:03 2012 (r239488) +++ releng/9.1/share/man/man5/moduli.5 Tue Aug 21 09:55:57 2012 (r239489) @@ -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 -.\" All rights reserved. +.\" Copyright (c) 2008 Damien Miller .\" -.\" 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