documentation for /etc/primes for wsimpson@greendragon.com, okay deraadt@,

markus@

2 files changed, 165 insertions, 3 deletions

diff --git a/share/man/man5/Makefile b/share/man/man5/Makefile
index 034fd8d8be1..2c71aa55dcb 100644
--- a/share/man/man5/Makefile
+++ b/share/man/man5/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.16 2001/01/29 02:11:13 niklas Exp $
+#	$OpenBSD: Makefile,v 1.17 2001/06/14 13:53:50 provos Exp $
 #	$NetBSD: Makefile,v 1.14 1995/05/11 23:13:15 cgd Exp $
 
 # missing: dump.5 plot.5
@@ -6,8 +6,9 @@
 MAN=	a.out.5 acct.5 bsd.port.mk.5 core.5 dir.5 disktab.5 ethers.5 fbtab.5 \
 	fs.5 fstab.5 group.5 hostname.if.5 hosts.equiv.5 hosts.5 intro.5 \
 	link.5 login.conf.5 motd.5 netgroup.5 networks.5 passwd.5 \
-	passwd.conf.5 phones.5 printcap.5 protocols.5 remote.5 resolv.conf.5 \
-	rpc.5 services.5 shells.5 stab.5 sysctl.conf.5 types.5 utmp.5
+	passwd.conf.5 phones.5 primes.5 printcap.5 protocols.5 remote.5 \
+	resolv.conf.5 rpc.5 services.5 shells.5 stab.5 sysctl.conf.5 \
+	types.5 utmp.5
 MLINKS= dir.5 dirent.5 fs.5 inode.5 utmp.5 wtmp.5 utmp.5 lastlog.5
 MLINKS+= hosts.equiv.5 .rhosts.5
 MLINKS+= resolv.conf.5 resolver.5
diff --git a/share/man/man5/primes.5 b/share/man/man5/primes.5
new file mode 100644
index 00000000000..44842591876
--- /dev/null
+++ b/share/man/man5/primes.5
@@ -0,0 +1,161 @@
+.\" $OpenBSD: primes.5,v 1.1 2001/06/14 13:53:50 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 PRIMES 5
+.Os
+.Sh NAME
+.Nm primes
+.Sh DESCRIPTION
+The
+.Pa /etc/primes
+file contains the system-wide Diffie-Hellman prime moduli for the
+.Xr photurisd 8
+and
+.Xr sshd 8
+programs.
+
+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/primes -compact
+.It Pa /etc/primes
+.El
+.Sh SEE ALSO
+.Xr photurisd 8 ,
+.Xr sshd 8
+.Sh HISTORY
+The
+.Nm
+file appeared in
+.Ox 2.8 .
+