Import OpenBSD's moduli(5) man page

1 files changed, 157 insertions, 0 deletions

diff --git a/share/man/man5/moduli.5 b/share/man/man5/moduli.5
new file mode 100644
index 0000000..69d060c
--- /dev/null
+++ b/share/man/man5/moduli.5
@@ -0,0 +1,157 @@
+.\" $OpenBSD: moduli.5,v 1.3 2001/06/24 18:50:52 provos Exp $
+.\"
+.\" Copyright 1997, 2000 William Allen Simpson <wsimpson@greendragon.com>
+.\" All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" 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 July 28, 1997
+.Dt MODULI 5
+.Os
+.Sh NAME
+.Nm moduli
+.Nd system moduli file
+.Sh DESCRIPTION
+The
+.Pa /etc/moduli
+file contains the system-wide Diffie-Hellman prime moduli for the
+.Xr photurisd 8
+and
+.Xr sshd 8
+programs.
+.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).
+.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.
+.Pp
+.Fa Type : decimal .
+Specifies the internal structure of the prime modulus.
+.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-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
+.Pp
+.Fa Tests : decimal (bit field) .
+Specifies the methods used in checking for primality.
+Usually, more than one test is used.
+.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.
+.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).
+.El
+.Pp
+.Fa Size : decimal .
+Specifies the number of significant bits.
+.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.
+.Sh FILES
+.Bl -tag -width /etc/moduli -compact
+.It Pa /etc/moduli
+.El
+.Sh SEE ALSO
+.Xr photurisd 8 ,
+.Xr sshd 8
+