IPSEC-RSASIGKEY(8)

💖 IPSEC-RSASIGKEY(8) 💖

okay bestie, welcome to the Executable programs corner of the manual, where the stars of the show are ipsec-rsasigkey — yes the whole thing, we're in the section 8 girlies now ✨

---

🌸 NAME 🌸

ipsec-rsasigkey — generate RSA signature key 🔑

like. it makes keys. signature keys specifically. that's the whole gig 🫶

---

✨ SYNOPSIS ✨

ipsec rsasigkey [--verbose] [--nssdir directory] [--nsspw password]
                [--seeddev device] [--seedbits bits]
                [--hostname hostname] [nbits]

yes the flags are literally sitting there in that little grid. copy it, don't improvise 💅

---

🦋 DESCRIPTION 🦋

so rsasigkey generates an RSA public/private key pair, suitable for digital signatures, of (exactly) nbits bits — and "exactly" is doing heavy lifting there, because that means two primes that are each exactly nbits/2 bits, plus the related numbers. then it emits the whole thing on standard output as ASCII data (mostly hex, bestie, mostly hex). and listen: nbits must be a multiple of 16. no exceptions, she said what she said.

the public exponent is forced to the value 3, which has important speed advantages for signature checking. iconic, efficient, we love her. BUT 🚨 — beware that the resulting keys have known weaknesses as encryption keys and should not be used for that purpose. like, not even a little. it's giving "signing only" energy.

the --verbose option makes rsasigkey give a running commentary on standard error. by default it works in silence until it is ready to generate output — mysterious, quiet, does not text back, then drops the key 💀

the --seeddev option specifies a source for random bits used to seed the crypto library's RNG. the default is /dev/random (see random(4)). history lesson real quick: FreeS/WAN and Openswan without NSS support used this option to specify the random source used to directly create keys. Libreswan, though? only uses it to seed the NSS crypto libraries RNG. also — under Linux with hardware random support, special devices might show up as /dev/*rng* devices. HOWEVER 🙈 these should never be accessed directly using this option, as hardware failures could lead to extremely non-random values (streams of zeroes have been observed in the wild). zeroes. in the wild. as a random stream. absolutely not.

the --seedbits option specifies how many seed bits are pulled from the random device to seed the NSS PRNG. the default of 480bit comes from FIPS requirements. seed bits are rounded up to a multiple of 8, little tidy-up moment ✨

the use of a different random device or a reduction of seedbits from the default value is prevented when the system is running in FIPS mode. FIPS said no and FIPS meant it.

the --nssdir option specifies the directory to use for the nss database. this is the directory where the NSS certificate, key and security modules databases reside. default value is /var/lib/ipsec/nss — commit that to memory, she comes back later 👑

the --password option specifies the nss cryptographic module authentication password if the NSS module has been configured to require it. a password is required by hardware tokens and also by the internal software token module when configured to run in FIPS mode. now here's the lil trick: if the argument is /etc/ipsec.d/nsspassword, the password comes from that file; otherwise the argument is the password. one argument, two very different meanings, iykyk 🤫

and finally, a fun fact for the group chat: the US patent on the RSA algorithm expired 20 Sept 2000. periodt. free real estate 🎀

---

🌈 OPTIONS 🌈

• --verbose — gives you a running commentary on standard error, so you're not just staring at a silent terminal wondering if she's okay.
• --nssdir directory — the directory to use for the nss database, i.e. where the NSS certificate, key and security modules databases live. default is /var/lib/ipsec/nss.
• --nsspw password — as spelled in the synopsis, the nss cryptographic module authentication password. (the description calls this one --password.) needed if the NSS module has been configured to require it — hardware tokens need it, and so does the internal software token module when configured to run in FIPS mode. if the argument is /etc/ipsec.d/nsspassword, the password is read from that file; otherwise the argument is the password.
• --seeddev device — the source for random bits used to seed the crypto library's RNG. default /dev/random (see random(4)). Libreswan only uses it to seed the NSS crypto libraries RNG (FreeS/WAN and Openswan without NSS support used it to specify the random source used to directly create keys). hardware /dev/*rng* devices? never point this at them directly, hardware failures can produce extremely non-random values, and streams of zeroes have literally been observed in the wild.
• --seedbits bits — how many seed bits get pulled from the random device to seed the NSS PRNG. default 480bit, straight from FIPS requirements. rounded up to a multiple of 8.
• --hostname hostname — sitting right there in the synopsis, bestie, keeping the lineup complete.
• nbits — how many bits the key is, exactly. must be a multiple of 16. the public exponent gets forced to 3 regardless, and heads up, keys made here have known weaknesses as encryption keys and should not be used for encryption. there's an internal limit on this, currently 20000 (more on that in BUGS).

🚨 reminder that a different random device or a reduction of seedbits from the default value is prevented when the system is running in FIPS mode. do not try it, she will not let you.

---

🍓 EXAMPLES 🍓

ipsec rsasigkey --verbose 4096

this one generates a 4096-bit signature key and stores this key in the NSS database. the public key can then be extracted and edited into the ipsec.conf (see ipsec-showhostkey(8)). chef's kiss, main character behavior, ate 💅

---

🧚 FILES 🧚

/dev/random, /dev/urandom

---

💜 SEE ALSO 💜

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

like yes bestie go read RFC 2537 and RFC 2313, they're right there, they're free, go off 📚

---

🕰️ HISTORY 🕰️

originally written for the Linux FreeS/WAN project <https://www.freeswan.org> by Henry Spencer. updated for the Libreswan Project by Paul Wouters. the lore is deep.

the --round and --noopt options were obsoleted as these were only used with the old non-library crypto code. gone but not forgotten 🙏

also the --random device is only used for seeding the crypto library, not for direct random to generate keys. important distinction, do not conflate them.

---

💀 BUGS 💀

there is an internal limit on nbits, currently 20000. that's the ceiling, bestie.

also rsasigkey's run time is difficult to predict, since /dev/random output can be arbitrarily delayed if the system's entropy pool is low on randomness, and the time taken by the search for primes is also somewhat unpredictable. specifically, embedded systems and most virtual machines are low on entropy 😭 in such a situation, consider generating the RSA key on another machine, and copying ipsec.secrets and the /var/lib/ipsec/nss directory tree to the embedded platform. note that NSS embeds the full path in the DB files, so the path on the proxy machine must be identical to the path on the destination machine. identical. no shortcuts. the vibes must match exactly.

---

👑 AUTHOR 👑

Andrew Cagney, Daniel Kahn Gillmor, D. Hugh Redelmeier, Harald Jenny, Jose Quaresma, Michael Richardson, Paul Wouters, Simon Deziel, Tuomo Soini

the whole friend group showed up for this one, we love a collaborative slay 🫶

---

and that's a wrap on Libreswan 5.4.1, dated 10/23/2026 — go forth, generate exactly-multiple-of-16-bit keys, and remember: exponent 3 for signatures, never for encryption. bye bestie, stay random ✨🌈💖