1IPSEC_RSASIGKEY(8)            Executable programs           IPSEC_RSASIGKEY(8)
2
3
4

NAME

6       ipsec_rsasigkey - generate RSA signature key
7

SYNOPSIS

9       ipsec rsasigkey [--verbose] [--seeddev device] [--seed numbits]
10             [--configdir nssdbdir] [--password nsspassword]
11             [--hostname hostname] [nbits]
12

DESCRIPTION

14       Rsasigkey generates an RSA public/private key pair, suitable for
15       digital signatures, of (exactly) nbits bits (that is, two primes each
16       of exactly nbits/2 bits, and related numbers) and emits it on standard
17       output as ASCII (mostly hex) data.  nbits must be a multiple of 16.
18
19       The public exponent is forced to the value 3, which has important speed
20       advantages for signature checking. Beware that the resulting keys have
21       known weaknesses as encryption keys and should not be used for that
22       purpose.
23
24       The --verbose option makes rsasigkey give a running commentary on
25       standard error. By default, it works in silence until it is ready to
26       generate output.
27
28       The --seeddev option specifies a source for random bits used to seed
29       the crypto library´s RNG. The default is /dev/random (see random(4)).
30       FreeS/WAN and Openswan without NSS support used this option to specify
31       the random source used to directly create keys. Libreswan only uses it
32       to seed the NSS crypto libraries RNG. Under Linux with hardware random
33       support, special devices might show up as /dev/*rng* devices. However,
34       these should never be accessed directly using this option, as hardware
35       failures could lead to extremely non-random values (streams of zeroes
36       have been observed in the wild)
37
38       The --seedbits option specifies how many seed bits are pulled from the
39       random device to seed the NSS PRNG. The default of 480bit comes from
40       FIPS requirements. Seed bits are rounded up to a multiple of 8.
41
42       The use of a different random device or a reduction of seedbits from
43       the default value is prevented when the system is running in FIPS mode.
44
45       The --configdir option specifies the nss configuration directory to
46       use. This is the directory where the NSS certificate, key and security
47       modules databases reside. The default value is /etc/ipsec.d.
48
49       The --password option specifies the nss cryptographic module
50       authentication password if the NSS module has been configured to
51       require it. A password is required by hardware tokens and also by the
52       internal software token module when configured to run in FIPS mode. If
53       the argument is configdir/nsspassword, the password comes from that
54       file; otherwise argument is the password.
55
56       The --hostname option specifies what host name to use in the first line
57       of the output (see below); the default is what gethostname(2) returns.
58
59       The output format looks like this (with long numbers trimmed down for
60       clarity):
61
62
63                # RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
64                # for signatures only, UNSAFE FOR ENCRYPTION
65                #pubkey=0sAQOF8tZ2NZt...Y1P+buFuFn/
66                Modulus: 0xcc2a86fcf440...cf1011abb82d1
67                PublicExponent: 0x03
68                # everything after this point is secret
69                PrivateExponent: 0x881c59fdf8...ab05c8c77d23
70                Prime1: 0xf49fd1f779...46504c7bf3
71                Prime2: 0xd5a9108453...321d43cb2b
72                Exponent1: 0xa31536a4fb...536d98adda7f7
73                Exponent2: 0x8e70b5ad8d...9142168d7dcc7
74                Coefficient: 0xafb761d001...0c13e98d98
75
76
77
78       The first (comment) line, indicating the nature and date of the key,
79       and giving a host name, is used by ipsec_showhostkey(8) when generating
80       some forms of key output.
81
82       The commented-out pubkey= line contains the public key, the public
83       exponent and the modulus combined in approximately RFC 2537 format (the
84       one deviation is that the combined value is given with a 0s prefix,
85       rather than in unadorned base-64), suitable for use in the ipsec.conf
86       file.
87
88       The Modulus, PublicExponent and PrivateExponent lines give the basic
89       signing and verification data.
90
91       The Prime1 and Prime2 lines give the primes themselves (aka p and q),
92       largest first. The Exponent1 and Exponent2 lines give the private
93       exponent mod p-1 and q-1 respectively. The Coefficient line gives the
94       Chinese Remainder Theorem coefficient, which is the inverse of q, mod
95       p. These additional numbers (which must all be kept as secret as the
96       private exponent) are precomputed aids to rapid signature generation.
97       When NSS is used, these values are not available outside the NSS
98       security database (software token or hardware token) and are instead
99       filled in with the CKA_ID.
100
101       No attempt is made to break long lines.
102
103       The US patent on the RSA algorithm expired 20 Sept 2000.
104

EXAMPLES

106       ipsec rsasigkey --verbose 4096 >mykey.txt
107           generates a 4096-bit signature key and puts it in the file
108           mykey.txt, with running commentary on standard error. The file
109           contents can be inserted verbatim into a suitable entry in the
110           ipsec.secrets file (see ipsec_secrets(5)), and the public key can
111           then be extracted and edited into the ipsec.conf (see
112           ipsec_showhostkey(8)).
113

FILES

115       /dev/random, /dev/urandom
116

SEE ALSO

118       random(4), rngd(8), ipsec_showhostkey(8), Applied Cryptography, 2nd.
119       ed., by Bruce Schneier, Wiley 1996, RFCs 2537, 2313, GNU MP, the GNU
120       multiple precision arithmetic library, edition 2.0.2, by Torbj Granlund
121

HISTORY

123       Originally written for the Linux FreeS/WAN project
124       <http://www.freeswan.org> by Henry Spencer. Updated for the Libreswan
125       Project by Paul Wouters.
126
127       The --round and --noopt options were obsoleted as these were only used
128       with the old non-library crypto code
129
130       The --random device is only used for seeding the crypto library, not
131       for direct random to generate keys
132

BUGS

134       There is an internal limit on nbits, currently 20000.
135
136       rsasigkey´s run time is difficult to predict, since /dev/random output
137       can be arbitrarily delayed if the system´s entropy pool is low on
138       randomness, and the time taken by the search for primes is also
139       somewhat unpredictable. Specifically, embedded systems and most virtual
140       machines are low on entropy. In such a situation, consider generating
141       the RSA key on another machine, and copying ipsec.secrets and the
142       ipsec.d/*db files to the embedded platform. Note that NSS embeds the
143       full path in the DB files, so the path on proxy machine must be
144       identical to the path on the destination machine.
145

AUTHOR

147       Paul Wouters
148           placeholder to suppress warning
149
150
151
152libreswan                         10/04/2017                IPSEC_RSASIGKEY(8)
Impressum