+'\" e
.\" -*-nroff-*-
.EQ
delim $$
Listen for incoming requests for key fragments and reply to them. The
default is to request key fragments.
.TP
-.BR "\-r, \-\-random=" seed-file
+.BI "\-r, \-\-random=" seed-file
Use (an initial portion of) the contents of
.I seed-file
to key the program's pseurorandom number generator. Since
.B udpkey
is intended to run early in a system's boot procedure, it's quite
unlikely that there's a great deal of high-quality entropy available.
-It's therefore useful to generate a key while the system is running, and
-store it somewhere where it can be found during early boot.
+It's therefore useful to generate a seed while the system is running,
+and store it somewhere where it can be found during early boot.
.SS Client operation
For each
.I source-spec
of the form
.IP
.IB address : port \c
-.IB [ = \c
+.RB [ = \c
.IR tag ] \c
-.IB [ # \c
+.RB [ # \c
.IR hash ] \c
.BR ; ...
.PP
fragment. The key fragment is located. If the key data is not a plain
binary string, or the key has no
.B clients
-attribute then the request is rejected. Otherwise the value of the
+attribute, then the request is rejected. Otherwise, the value of the
.B clients
attribute is expected to take the form
.IP
program uses the Catacomb keyring format to store its cryptographic
keys: see
.BR keyring (5)
-for the technical details. Keys maybe generated and managed using the
+for the technical details. Keys may be generated and managed using the
.BR key (1)
utility.
.PP
The security of
.BR udpkey 's
protocol (described below, for those who care about such things) is
-based on the difficulty of the \*(DH in cyclic groups. The client need
-to know the private key; the server need only know the public part.
-Both ends must agree on the attributes associated with the key.
+based on the difficulty of \*(DH problems in cyclic groups. The client
+needs to know the private key; the server need only know the public
+part. Both ends must agree on the attributes associated with the key.
.PP
Two types of \*(DH groups are supported. The group type is determined
from the appropriate key's
.TP
.B dh
Plain old \*(DH, in a Schnorr group \(en i.e., a prime-order subgroup of
-a the multiplicative group of a prime-order finite field. An
-appropriate key may be generated using a command such as
+the multiplicative group of a prime-order finite field. An appropriate
+key may be generated using a command such as
.RS
.IP
.nf
curve. Catacomb's
.BR key (1)
program can't generate such groups, though it knows of a number of
-suitable examples, or you can use your own curves. An appropriate man
-be generated using a command such as
+suitable examples, or you can use your own curves. An appropriate key
+can be generated using a command such as
.RS
.IP
.BI "key add \-t" tag " \-aec \-Cnist-p256 udpkey-kem group=ec \fR..."
.B mac
The message authentication code used to ensure the integrity of the
ciphertext, in the form
-.IB name / tagbits \fR.
-The default is to use HMAC with the chosen hash function, and truncate
+.IB name\fR[ / tagbits \fR].
+The defaults are to use HMAC with the chosen hash function, and truncate
the tag to half of its original length.
.PP
Key fragments must contain only plain binary data: you can generate one
.SS Protocol description
Let $G$ be a cyclic group with prime order $q$; we consider this as a
one-dimensional vector space over the finite field ${roman GF}(q)$. Let
-$P$ be any nonzero element of the group.
+$P$ be any nonzero vector.
.PP
The client's private key is a scalar $x$; its public key is the
corresponding vector $X = x P$. When constructing a request, a client
followed by a representation of the vector $U$.
.PP
When constructing a response, a server selects random scalars $v$ and
-$r$, and computes $U = u P$ and $R = r P$. It then determines $Y = v U$
+$r$, and computes $V = v P$ and $R = r P$. It then determines $Y = v U$
and $Z = r X$, and hashes $R$ and $Z$ to obtain keys for a symmetric
cipher and MAC. It encrypts the key fragment and authenticates the
resulting ciphertext. Finally, the response consists of the vectors $V$
hashing $R$ and $Z$. Therefore it can recover $Y = R - W$, which solves
an instance of the harder
.I Computational
-(actually, Gap) \*(DH problem in $G$. This analysis can be made
-rigorous and quantitative.
+(actually, Gap) \*(DH problem in $G$.
+.IP
+This analysis can be made rigorous and quantitative.
.hP \*o
Neither side attempts to authenticate the other explicitly. The server
implicitly authenticates the client by encrypting its key fragment using
the client's public key. (This encryption is standard DLIES, and
-security again depends on the Gap \*(DH problem in $G$.) The client
+security again depends on the Gap \*(DH problem in $G$.) The client
doesn't attempt to authenticate the server at all, though it can check
that the response is correct by comparing its hash to a known copy; this
confirms that the received key fragment is correct, and the client has
when high-quality entropy is available \(en serves to limit the exposure
to responses captured since the last rekeying.
.SH BUGS
-For some mysterious reason,
-.BR cryptsetup (8)
-initially rejects a key from
-.BR udpkey ;
-but when the relevant
-.B initramfs
-script retries, everything works. I'm not sure what's going on here.
+None known.
.SH SEE ALSO
.BR key (1),
.BR crypttab (5),