| 1 |
.\" $OpenBSD: moduli.5,v 1.19 2022/04/16 04:30:10 dtucker Exp $ |
| 2 |
.\" |
| 3 |
.\" Copyright (c) 2008 Damien Miller <[email protected]> |
| 4 |
.\" |
| 5 |
.\" Permission to use, copy, modify, and distribute this software for any |
| 6 |
.\" purpose with or without fee is hereby granted, provided that the above |
| 7 |
.\" copyright notice and this permission notice appear in all copies. |
| 8 |
.\" |
| 9 |
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES |
| 10 |
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF |
| 11 |
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR |
| 12 |
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
| 13 |
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN |
| 14 |
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
| 15 |
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
| 16 |
.Dd $Mdocdate: April 16 2022 $ |
| 17 |
.Dt MODULI 5 |
| 18 |
.Os |
| 19 |
.Sh NAME |
| 20 |
.Nm moduli |
| 21 |
.Nd Diffie-Hellman moduli |
| 22 |
.Sh DESCRIPTION |
| 23 |
The |
| 24 |
.Pa /etc/ssh/moduli |
| 25 |
file contains prime numbers and generators for use by |
| 26 |
.Xr sshd 8 |
| 27 |
in the Diffie-Hellman Group Exchange key exchange method. |
| 28 |
.Pp |
| 29 |
New moduli may be generated with |
| 30 |
.Xr ssh-keygen 1 |
| 31 |
using a two-step process. |
| 32 |
An initial |
| 33 |
.Em candidate generation |
| 34 |
pass, using |
| 35 |
.Ic ssh-keygen -M generate , |
| 36 |
calculates numbers that are likely to be useful. |
| 37 |
A second |
| 38 |
.Em primality testing |
| 39 |
pass, using |
| 40 |
.Ic ssh-keygen -M screen , |
| 41 |
provides a high degree of assurance that the numbers are prime and are |
| 42 |
safe for use in Diffie-Hellman operations by |
| 43 |
.Xr sshd 8 . |
| 44 |
This |
| 45 |
.Nm |
| 46 |
format is used as the output from each pass. |
| 47 |
.Pp |
| 48 |
The file consists of newline-separated records, one per modulus, |
| 49 |
containing seven space-separated fields. |
| 50 |
These fields are as follows: |
| 51 |
.Bl -tag -width Description -offset indent |
| 52 |
.It timestamp |
| 53 |
The time that the modulus was last processed as YYYYMMDDHHMMSS. |
| 54 |
.It type |
| 55 |
Decimal number specifying the internal structure of the prime modulus. |
| 56 |
Supported types are: |
| 57 |
.Pp |
| 58 |
.Bl -tag -width 0x00 -compact |
| 59 |
.It 0 |
| 60 |
Unknown, not tested. |
| 61 |
.It 2 |
| 62 |
"Safe" prime; (p-1)/2 is also prime. |
| 63 |
.It 4 |
| 64 |
Sophie Germain; 2p+1 is also prime. |
| 65 |
.El |
| 66 |
.Pp |
| 67 |
Moduli candidates initially produced by |
| 68 |
.Xr ssh-keygen 1 |
| 69 |
are Sophie Germain primes (type 4). |
| 70 |
Further primality testing with |
| 71 |
.Xr ssh-keygen 1 |
| 72 |
produces safe prime moduli (type 2) that are ready for use in |
| 73 |
.Xr sshd 8 . |
| 74 |
Other types are not used by OpenSSH. |
| 75 |
.It tests |
| 76 |
Decimal number indicating the type of primality tests that the number |
| 77 |
has been subjected to represented as a bitmask of the following values: |
| 78 |
.Pp |
| 79 |
.Bl -tag -width 0x00 -compact |
| 80 |
.It 0x00 |
| 81 |
Not tested. |
| 82 |
.It 0x01 |
| 83 |
Composite number \(en not prime. |
| 84 |
.It 0x02 |
| 85 |
Sieve of Eratosthenes. |
| 86 |
.It 0x04 |
| 87 |
Probabilistic Miller-Rabin primality tests. |
| 88 |
.El |
| 89 |
.Pp |
| 90 |
The |
| 91 |
.Xr ssh-keygen 1 |
| 92 |
moduli candidate generation uses the Sieve of Eratosthenes (flag 0x02). |
| 93 |
Subsequent |
| 94 |
.Xr ssh-keygen 1 |
| 95 |
primality tests are Miller-Rabin tests (flag 0x04). |
| 96 |
.It trials |
| 97 |
Decimal number indicating the number of primality trials |
| 98 |
that have been performed on the modulus. |
| 99 |
.It size |
| 100 |
Decimal number indicating the size of the prime in bits. |
| 101 |
.It generator |
| 102 |
The recommended generator for use with this modulus (hexadecimal). |
| 103 |
.It modulus |
| 104 |
The modulus itself in hexadecimal. |
| 105 |
.El |
| 106 |
.Pp |
| 107 |
When performing Diffie-Hellman Group Exchange, |
| 108 |
.Xr sshd 8 |
| 109 |
first estimates the size of the modulus required to produce enough |
| 110 |
Diffie-Hellman output to sufficiently key the selected symmetric cipher. |
| 111 |
.Xr sshd 8 |
| 112 |
then randomly selects a modulus from |
| 113 |
.Fa /etc/ssh/moduli |
| 114 |
that best meets the size requirement. |
| 115 |
.Sh SEE ALSO |
| 116 |
.Xr ssh-keygen 1 , |
| 117 |
.Xr sshd 8 |
| 118 |
.Sh STANDARDS |
| 119 |
.Rs |
| 120 |
.%A M. Friedl |
| 121 |
.%A N. Provos |
| 122 |
.%A W. Simpson |
| 123 |
.%D March 2006 |
| 124 |
.%R RFC 4419 |
| 125 |
.%T Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol |
| 126 |
.Re |