Merge branch 'master' of git.distorted.org.uk:~mdw/publish/public-git/catacomb

[u/mdw/catacomb] / key.1

diff --git a/key.1 b/key.1
index 6aa3520..3e7a601 100644 (file)
--- a/key.1
+++ b/key.1
@@ -48,7 +48,7 @@ is one of:
 .RI [ item ...]
 .br
 .B add
 .RI [ item ...]
 .br
 .B add

-.RB [ \-lqrLS ]
+.RB [ \-lqrLKS ]

 .RB [ \-a
 .IR alg ]
 .RB [ \-b | \-B
 .RB [ \-a
 .IR alg ]
 .RB [ \-b | \-B


@@ -98,6 +98,10 @@ is one of:
 .I tag
 .IR attr ...
 .br
 .I tag
 .IR attr ...
 .br

+.B getattr
+.I tag
+.I attr
+.br

 .B lock
 .I qtag
 .br
 .B lock
 .I qtag
 .br


@@ -458,12 +462,17 @@ using a passphrase.
 Suppresses the progress indication which is usually generated while
 time-consuming key generation tasks are being performed.
 .TP
 Suppresses the progress indication which is usually generated while
 time-consuming key generation tasks are being performed.
 .TP

-.BI "\-L, --lim-lee"
+.BI "\-L, \-\-lim-lee"

 When generating Diffie-Hellman parameters, generate a Lim-Lee prime
 rather than a random (or safe) prime.  See the details on Diffie-Hellman
 key generation below.
 .TP
 When generating Diffie-Hellman parameters, generate a Lim-Lee prime
 rather than a random (or safe) prime.  See the details on Diffie-Hellman
 key generation below.
 .TP

-.BI "\-S, --subgroup"
+.BI "\-K, \-\-kcdsa"
+When generating Diffie-Hellman parameters, generate a KCDSA-style
+Lim-Lee prime rather than a random (or safe) prime.  See the details on
+Diffie-Hellman key generation below.
+.TP
+.BI "\-S, \-\-subgroup"

 When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
 generator of a prime-order subgroup rather than a subgroup of order
 .RI ( p "- 1)/2."
 When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
 generator of a prime-order subgroup rather than a subgroup of order
 .RI ( p "- 1)/2."


@@ -570,11 +579,11 @@ option controls the size of the modulus
 .IR p ;
 the default size is 1024 bits.
 .IP
 .IR p ;
 the default size is 1024 bits.
 .IP

-If no 
+If no

 .I q
 size is selected using the
 .B \-B
 .I q
 size is selected using the
 .B \-B

-option and the Lim-Lee prime option is disabled, then 
+option and the Lim-Lee prime options are disabled, then

 .I p
 is chosen to be a `safe' prime (i.e.,
 .IR p \ =\ 2 q \ +\ 1,
 .I p
 is chosen to be a `safe' prime (i.e.,
 .IR p \ =\ 2 q \ +\ 1,


@@ -598,7 +607,7 @@ is a multiple of
 .IP
 If the
 .B \-L
 .IP
 If the
 .B \-L

-option was given Lim-Lee primes are selected: the parameters are chosen
+option was given, Lim-Lee primes are selected: the parameters are chosen

 such that
 .IR p \ =\ 2\  q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
 where the
 such that
 .IR p \ =\ 2\  q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
 where the


@@ -608,8 +617,22 @@ are primes at least as large as the setting given by the
 option (or 256 bits, if no setting was given).
 .IP
 If the
 option (or 256 bits, if no setting was given).
 .IP
 If the

+.B \-K
+option was given, KCDSA-style Lim-Lee primes are selected: the
+parameters are chosen such that
+.IR p \ =\ 2\  q\ v \ +\ 1,
+where
+.IR p,
+.I q
+and
+.I v
+are primes.
+.IP
+If the

 .B \-S
 .B \-S

-option was given, the generator
+or
+.B \-K
+options were given, the generator

 .I g
 is chosen to generate the subgroup of order
 .IR q \*(us0\*(ue;
 .I g
 is chosen to generate the subgroup of order
 .IR q \*(us0\*(ue;


@@ -752,7 +775,7 @@ if the field type is
 then an optional
 .RB ` , '
 and the representation of the normal element \*(*b; an optional
 then an optional
 .RB ` , '
 and the representation of the normal element \*(*b; an optional

-.RB ` / ';
+.RB ` ; ';

 a
 .IR "curve type" ,
 which is one of
 a
 .IR "curve type" ,
 which is one of


@@ -767,14 +790,14 @@ an optional
 the two field-element parameters
 .I a
 and
 the two field-element parameters
 .I a
 and

-.IR b 
+.IR b

 which define the elliptic curve
 .IR E ,
 separated by an optional
 .RB ` , ';
 an optional
 which define the elliptic curve
 .IR E ,
 separated by an optional
 .RB ` , ';
 an optional

-.RB ` / ';
-the 
+.RB ` ; ';
+the

 .IR x -
 and
 .IR y -coordinates
 .IR x -
 and
 .IR y -coordinates


@@ -786,11 +809,11 @@ an optional
 .RB ` : ';
 the order
 .I r
 .RB ` : ';
 the order
 .I r

-of the group generated by 
+of the group generated by

 .IR G ;
 an optional
 .RB ` * ';
 .IR G ;
 an optional
 .RB ` * ';

-and the 
+and the

 .I cofactor
 .I h
 =
 .I cofactor
 .I h
 =


@@ -836,6 +859,13 @@ An attribute can be deleted by assigning it an empty value.  Although
 the keyring file format is capable of representing an attribute with an
 empty value as distinct from a nonexistant attribute, this interface
 does not allow empty attributes to be set.
 the keyring file format is capable of representing an attribute with an
 empty value as distinct from a nonexistant attribute, this interface
 does not allow empty attributes to be set.

+.SS "getattr"
+Fetches a single attribute of a key.  The key whose attribute is to be
+read is given by its
+.IR tag .
+The attribute's value is written to standard output followed by a
+newline.  If the key or attribute is absent, a message is written to
+standard error and the program exits nonzero.

 .SS "comment"
 Sets, deletes or changes the comment attached to a key.  The first
 argument is a key tag or keyid which names the key to be modified; the
 .SS "comment"
 Sets, deletes or changes the comment attached to a key.  The first
 argument is a key tag or keyid which names the key to be modified; the