'\" t
.\"     Title: IPSEC_ECDSASIGKEY
.\"    Author: Paul Wouters
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 08/10/2023
.\"    Manual: Executable programs
.\"    Source: libreswan
.\"  Language: English
.\"
.TH "IPSEC_ECDSASIGKEY" "8" "08/10/2023" "libreswan" "Executable programs"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ipsec_ecdsasigkey \- generate ECDSA signature key
.SH "SYNOPSIS"
.HP \w'\fBipsec\fR\ 'u
\fBipsec\fR \fIecdsasigkey\fR [\-\-verbose] [\-\-seeddev\ \fIdevice\fR] [\-\-seed\ \fInumbits\fR] [\-\-nssdir\ \fInssdir\fR] [\-\-password\ \fInsspassword\fR] [\-\-hostname\ \fIhostname\fR] [curvename]
.SH "DESCRIPTION"
.PP
\fIecdsasigkey\fR
generates an ECDSA public/private key pair, suitable for digital signatures, on a named curve specified with
\fIcurvename\fR\&. Currently it only accepts
\fIsecp256r1\fR,
\fIsecp384r1\fR, and
\fIsecp521r1\fR\&.
.PP
The public exponent is forced to the value
\fB3\fR, which has important speed advantages for signature checking\&. Beware that the resulting keys have known weaknesses as encryption keys
\fBand should not be used for that purpose\fR\&.
.PP
The
\fB\-\-verbose\fR
option makes
\fIecdsasigkey\fR
give a running commentary on standard error\&. By default, it works in silence until it is ready to generate output\&.
.PP
The
\fB\-\-seeddev\fR
option specifies a source for random bits used to seed the crypto library\*(Aqs RNG\&. The default is
/dev/random
(see
\fBrandom\fR(4))\&. FreeS/WAN and Openswan without NSS support used this option to specify the random source used to directly create keys\&. Libreswan only uses it to seed the NSS crypto libraries RNG\&. 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)
.PP
The
\fB\-\-seedbits\fR
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\&.
.PP
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\&.
.PP
The
\fB\-\-nssdir\fR
option specifies the directory to use for the nss database\&. This is the directory where the NSS certificate, key and security modules databases reside\&. The default value is
/var/lib/ipsec/nss\&.
.PP
The
\fB\-\-password\fR
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\&. If the argument is
\fI/etc/ipsec\&.d\fR/nsspassword, the password comes from that file; otherwise argument is the password\&.
.SH "EXAMPLES"
.PP
\fBipsec ecdsasigkey \-\-verbose 4096 \fR
.RS 4
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
\fBipsec_showhostkey\fR(8))\&.
.RE
.SH "FILES"
.PP
/dev/random, /dev/urandom
.SH "SEE ALSO"
.PP
\fBrandom\fR(4),
\fBrngd\fR(8),
\fBipsec_showhostkey\fR(8),
\fIApplied Cryptography, 2nd\&. ed\&., by Bruce Schneier, Wiley 1996\fR,
\fIRFCs 2537, 2313\fR,
\fIGNU MP, the GNU multiple precision arithmetic library, edition 2\&.0\&.2, by Torbj Granlund\fR
.SH "HISTORY"
.PP
Originally written for the Linux FreeS/WAN project <\m[blue]\fBhttps://www\&.freeswan\&.org\fR\m[]> by Henry Spencer\&. Updated for the Libreswan Project by Paul Wouters\&.
.PP
The
\fI\-\-round\fR
and
\fI\-\-noopt\fR
options were obsoleted as these were only used with the old non\-library crypto code
.PP
The
\fI\-\-random\fR
device is only used for seeding the crypto library, not for direct random to generate keys
.SH "BUGS"
.PP
\fIecdsasigkey\fR\*(Aqs run time is difficult to predict, since
/dev/random
output can be arbitrarily delayed if the system\*(Aqs 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 ECDSA 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 proxy machine must be identical to the path on the destination machine\&.
.SH "AUTHOR"
.PP
\fBPaul Wouters\fR
.RS 4
placeholder to suppress warning
.RE