ssh-keygen(1): -a is missing in SYNOPSIS and small wording change

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

ssh-keygen(1): -a is missing in SYNOPSIS and small wording change

Solene Rapenne
I found that ssh-keygen(1) missed mention of -a flag in SYNOPSIS.

The following patch adds mention to [-a rounds] with default (no
flag), -p, -c, -K and -A

All the functions triggered by these flags use the rounds variable
defined with -a parameter (default 0)


I also propose a small wording change, in the sentence:
"After a key is generated, instructions below detail [...]"

I thought below refered to the list of options after that sentence,
but it may be a mistake of mine here.


Index: ssh-keygen.1
===================================================================
RCS file: /cvs/src/usr.bin/ssh/ssh-keygen.1,v
retrieving revision 1.203
diff -u -p -r1.203 ssh-keygen.1
--- ssh-keygen.1 3 Apr 2020 02:26:56 -0000 1.203
+++ ssh-keygen.1 25 Jun 2020 16:28:54 -0000
@@ -44,6 +44,7 @@
 .Sh SYNOPSIS
 .Nm ssh-keygen
 .Op Fl q
+.Op Fl a Ar rounds
 .Op Fl b Ar bits
 .Op Fl C Ar comment
 .Op Fl f Ar output_keyfile
@@ -54,6 +55,7 @@
 .Op Fl w Ar provider
 .Nm ssh-keygen
 .Fl p
+.Op Fl a Ar rounds
 .Op Fl f Ar keyfile
 .Op Fl m Ar format
 .Op Fl N Ar new_passphrase
@@ -71,6 +73,7 @@
 .Op Fl f Ar input_keyfile
 .Nm ssh-keygen
 .Fl c
+.Op Fl a Ar rounds
 .Op Fl C Ar comment
 .Op Fl f Ar keyfile
 .Op Fl P Ar passphrase
@@ -93,6 +96,7 @@
 .Op Fl f Ar known_hosts_file
 .Nm ssh-keygen
 .Fl K
+.Op Fl a Ar rounds
 .Op Fl w Ar provider
 .Nm ssh-keygen
 .Fl R Ar hostname
@@ -125,6 +129,7 @@
 .Op Fl f Ar input_keyfile
 .Nm ssh-keygen
 .Fl A
+.Op Fl a Ar rounds
 .Op Fl f Ar prefix_path
 .Nm ssh-keygen
 .Fl k
@@ -248,7 +253,9 @@ keys may be converted using this option
 .Fl p
 (change passphrase) flag.
 .Pp
-After a key is generated, instructions below detail where the keys
+After a key is generated,
+.Nm
+will ask where the keys
 should be placed to be activated.
 .Pp
 The options are as follows:

Reply | Threaded
Open this post in threaded view
|

Re: ssh-keygen(1): -a is missing in SYNOPSIS and small wording change

Jason McIntyre-2
On Thu, Jun 25, 2020 at 06:40:36PM +0200, Solene Rapenne wrote:
> I found that ssh-keygen(1) missed mention of -a flag in SYNOPSIS.
>

i think this got accidently removed in -r1.184:

        remove single letter flags for moduli operations

> The following patch adds mention to [-a rounds] with default (no
> flag), -p, -c, -K and -A
>

i'm definitely not the right person to ok that

> All the functions triggered by these flags use the rounds variable
> defined with -a parameter (default 0)
>
>
> I also propose a small wording change, in the sentence:
> "After a key is generated, instructions below detail [...]"
>
> I thought below refered to the list of options after that sentence,
> but it may be a mistake of mine here.
>

i wanted to ask about this text too. it's unclear to me. after a key is
generated, ssh-keygen asks where to save it. i wonder why we use the
wording "should be placed to be activated"? it seems odd, but maybe
there's a reason.

jmc

>
> Index: ssh-keygen.1
> ===================================================================
> RCS file: /cvs/src/usr.bin/ssh/ssh-keygen.1,v
> retrieving revision 1.203
> diff -u -p -r1.203 ssh-keygen.1
> --- ssh-keygen.1 3 Apr 2020 02:26:56 -0000 1.203
> +++ ssh-keygen.1 25 Jun 2020 16:28:54 -0000
> @@ -44,6 +44,7 @@
>  .Sh SYNOPSIS
>  .Nm ssh-keygen
>  .Op Fl q
> +.Op Fl a Ar rounds
>  .Op Fl b Ar bits
>  .Op Fl C Ar comment
>  .Op Fl f Ar output_keyfile
> @@ -54,6 +55,7 @@
>  .Op Fl w Ar provider
>  .Nm ssh-keygen
>  .Fl p
> +.Op Fl a Ar rounds
>  .Op Fl f Ar keyfile
>  .Op Fl m Ar format
>  .Op Fl N Ar new_passphrase
> @@ -71,6 +73,7 @@
>  .Op Fl f Ar input_keyfile
>  .Nm ssh-keygen
>  .Fl c
> +.Op Fl a Ar rounds
>  .Op Fl C Ar comment
>  .Op Fl f Ar keyfile
>  .Op Fl P Ar passphrase
> @@ -93,6 +96,7 @@
>  .Op Fl f Ar known_hosts_file
>  .Nm ssh-keygen
>  .Fl K
> +.Op Fl a Ar rounds
>  .Op Fl w Ar provider
>  .Nm ssh-keygen
>  .Fl R Ar hostname
> @@ -125,6 +129,7 @@
>  .Op Fl f Ar input_keyfile
>  .Nm ssh-keygen
>  .Fl A
> +.Op Fl a Ar rounds
>  .Op Fl f Ar prefix_path
>  .Nm ssh-keygen
>  .Fl k
> @@ -248,7 +253,9 @@ keys may be converted using this option
>  .Fl p
>  (change passphrase) flag.
>  .Pp
> -After a key is generated, instructions below detail where the keys
> +After a key is generated,
> +.Nm
> +will ask where the keys
>  should be placed to be activated.
>  .Pp
>  The options are as follows:
>

Reply | Threaded
Open this post in threaded view
|

Re: ssh-keygen(1): -a is missing in SYNOPSIS and small wording change

Solene Rapenne
On Thu, 25 Jun 2020 18:02:23 +0100
Jason McIntyre <[hidden email]>:

> On Thu, Jun 25, 2020 at 06:40:36PM +0200, Solene Rapenne wrote:
> > I found that ssh-keygen(1) missed mention of -a flag in SYNOPSIS.
> >  
>
> i think this got accidently removed in -r1.184:
>
> remove single letter flags for moduli operations
>
> > The following patch adds mention to [-a rounds] with default (no
> > flag), -p, -c, -K and -A
> >  
>
> i'm definitely not the right person to ok that
>
> > All the functions triggered by these flags use the rounds variable
> > defined with -a parameter (default 0)
> >
> >
> > I also propose a small wording change, in the sentence:
> > "After a key is generated, instructions below detail [...]"
> >
> > I thought below refered to the list of options after that sentence,
> > but it may be a mistake of mine here.
> >  
>
> i wanted to ask about this text too. it's unclear to me. after a key is
> generated, ssh-keygen asks where to save it. i wonder why we use the
> wording "should be placed to be activated"? it seems odd, but maybe
> there's a reason.
>
> jmc

I don't really understand the whole sentence but I thought it was
due to my english understanding.

New patch adding [-a rounds] in ssh-keygen usage(). I'm not sure
if the first line of usage() output is ok or too long now.

Index: ssh-keygen.1
===================================================================
RCS file: /cvs/src/usr.bin/ssh/ssh-keygen.1,v
retrieving revision 1.203
diff -u -p -r1.203 ssh-keygen.1
--- ssh-keygen.1 3 Apr 2020 02:26:56 -0000 1.203
+++ ssh-keygen.1 13 Jul 2020 20:34:14 -0000
@@ -44,6 +44,7 @@
 .Sh SYNOPSIS
 .Nm ssh-keygen
 .Op Fl q
+.Op Fl a Ar rounds
 .Op Fl b Ar bits
 .Op Fl C Ar comment
 .Op Fl f Ar output_keyfile
@@ -54,6 +55,7 @@
 .Op Fl w Ar provider
 .Nm ssh-keygen
 .Fl p
+.Op Fl a Ar rounds
 .Op Fl f Ar keyfile
 .Op Fl m Ar format
 .Op Fl N Ar new_passphrase
@@ -71,6 +73,7 @@
 .Op Fl f Ar input_keyfile
 .Nm ssh-keygen
 .Fl c
+.Op Fl a Ar rounds
 .Op Fl C Ar comment
 .Op Fl f Ar keyfile
 .Op Fl P Ar passphrase
@@ -93,6 +96,7 @@
 .Op Fl f Ar known_hosts_file
 .Nm ssh-keygen
 .Fl K
+.Op Fl a Ar rounds
 .Op Fl w Ar provider
 .Nm ssh-keygen
 .Fl R Ar hostname
@@ -125,6 +129,7 @@
 .Op Fl f Ar input_keyfile
 .Nm ssh-keygen
 .Fl A
+.Op Fl a Ar rounds
 .Op Fl f Ar prefix_path
 .Nm ssh-keygen
 .Fl k
@@ -248,7 +253,9 @@ keys may be converted using this option
 .Fl p
 (change passphrase) flag.
 .Pp
-After a key is generated, instructions below detail where the keys
+After a key is generated,
+.Nm
+will ask where the keys
 should be placed to be activated.
 .Pp
 The options are as follows:
Index: ssh-keygen.c
===================================================================
RCS file: /cvs/src/usr.bin/ssh/ssh-keygen.c,v
retrieving revision 1.413
diff -u -p -r1.413 ssh-keygen.c
--- ssh-keygen.c 26 Jun 2020 05:02:03 -0000 1.413
+++ ssh-keygen.c 13 Jul 2020 20:34:15 -0000
@@ -3013,15 +3013,15 @@ static void
 usage(void)
 {
  fprintf(stderr,
-    "usage: ssh-keygen [-q] [-b bits] [-C comment] [-f output_keyfile] [-m format]\n"
+    "usage: ssh-keygen [-q] [-a rounds] [-b bits] [-C comment] [-f output_keyfile] [-m format]\n"
     "                  [-t dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa]\n"
     "                  [-N new_passphrase] [-O option] [-w provider]\n"
-    "       ssh-keygen -p [-f keyfile] [-m format] [-N new_passphrase]\n"
+    "       ssh-keygen -p [-a rounds] [-f keyfile] [-m format] [-N new_passphrase]\n"
     "                   [-P old_passphrase]\n"
     "       ssh-keygen -i [-f input_keyfile] [-m key_format]\n"
     "       ssh-keygen -e [-f input_keyfile] [-m key_format]\n"
     "       ssh-keygen -y [-f input_keyfile]\n"
-    "       ssh-keygen -c [-C comment] [-f keyfile] [-P passphrase]\n"
+    "       ssh-keygen -c [-a rounds] [-C comment] [-f keyfile] [-P passphrase]\n"
     "       ssh-keygen -l [-v] [-E fingerprint_hash] [-f input_keyfile]\n"
     "       ssh-keygen -B [-f input_keyfile]\n");
 #ifdef ENABLE_PKCS11
@@ -3031,7 +3031,7 @@ usage(void)
  fprintf(stderr,
     "       ssh-keygen -F hostname [-lv] [-f known_hosts_file]\n"
     "       ssh-keygen -H [-f known_hosts_file]\n"
-    "       ssh-keygen -K [-w provider]\n"
+    "       ssh-keygen -K [-a rounds] [-w provider]\n"
     "       ssh-keygen -R hostname [-f known_hosts_file]\n"
     "       ssh-keygen -r hostname [-g] [-f input_keyfile]\n"
 #ifdef WITH_OPENSSL
@@ -3042,7 +3042,7 @@ usage(void)
     "                  [-n principals] [-O option] [-V validity_interval]\n"
     "                  [-z serial_number] file ...\n"
     "       ssh-keygen -L [-f input_keyfile]\n"
-    "       ssh-keygen -A [-f prefix_path]\n"
+    "       ssh-keygen -A [-a rounds] [-f prefix_path]\n"
     "       ssh-keygen -k -f krl_file [-u] [-s ca_public] [-z version_number]\n"
     "                  file ...\n"
     "       ssh-keygen -Q [-l] -f krl_file [file ...]\n"

Reply | Threaded
Open this post in threaded view
|

Re: ssh-keygen(1): -a is missing in SYNOPSIS and small wording change

Jason McIntyre-2
On Mon, Jul 13, 2020 at 10:36:45PM +0200, Solene Rapenne wrote:

> On Thu, 25 Jun 2020 18:02:23 +0100
> Jason McIntyre <[hidden email]>:
>
> > On Thu, Jun 25, 2020 at 06:40:36PM +0200, Solene Rapenne wrote:
> > > I found that ssh-keygen(1) missed mention of -a flag in SYNOPSIS.
> > >  
> >
> > i think this got accidently removed in -r1.184:
> >
> > remove single letter flags for moduli operations
> >
> > > The following patch adds mention to [-a rounds] with default (no
> > > flag), -p, -c, -K and -A
> > >  
> >
> > i'm definitely not the right person to ok that
> >
> > > All the functions triggered by these flags use the rounds variable
> > > defined with -a parameter (default 0)
> > >
> > >
> > > I also propose a small wording change, in the sentence:
> > > "After a key is generated, instructions below detail [...]"
> > >
> > > I thought below refered to the list of options after that sentence,
> > > but it may be a mistake of mine here.
> > >  
> >
> > i wanted to ask about this text too. it's unclear to me. after a key is
> > generated, ssh-keygen asks where to save it. i wonder why we use the
> > wording "should be placed to be activated"? it seems odd, but maybe
> > there's a reason.
> >
> > jmc
>
> I don't really understand the whole sentence but I thought it was
> due to my english understanding.
>
> New patch adding [-a rounds] in ssh-keygen usage(). I'm not sure
> if the first line of usage() output is ok or too long now.
>

morning.

it does indeed look horrible, but somehow the page currently has -t in
the wrong place, so that may help. i suggest you try to get it like
this:

        ... [-f output_keyfile]
        [-m format] [-N new_passphrase] [-O option]
        [-t ...]
        [-w provider]

in the man source, that will mean rearranging -t to list it after -O and
before -w. that will format a bit more nicely too.

jmc

> Index: ssh-keygen.1
> ===================================================================
> RCS file: /cvs/src/usr.bin/ssh/ssh-keygen.1,v
> retrieving revision 1.203
> diff -u -p -r1.203 ssh-keygen.1
> --- ssh-keygen.1 3 Apr 2020 02:26:56 -0000 1.203
> +++ ssh-keygen.1 13 Jul 2020 20:34:14 -0000
> @@ -44,6 +44,7 @@
>  .Sh SYNOPSIS
>  .Nm ssh-keygen
>  .Op Fl q
> +.Op Fl a Ar rounds
>  .Op Fl b Ar bits
>  .Op Fl C Ar comment
>  .Op Fl f Ar output_keyfile
> @@ -54,6 +55,7 @@
>  .Op Fl w Ar provider
>  .Nm ssh-keygen
>  .Fl p
> +.Op Fl a Ar rounds
>  .Op Fl f Ar keyfile
>  .Op Fl m Ar format
>  .Op Fl N Ar new_passphrase
> @@ -71,6 +73,7 @@
>  .Op Fl f Ar input_keyfile
>  .Nm ssh-keygen
>  .Fl c
> +.Op Fl a Ar rounds
>  .Op Fl C Ar comment
>  .Op Fl f Ar keyfile
>  .Op Fl P Ar passphrase
> @@ -93,6 +96,7 @@
>  .Op Fl f Ar known_hosts_file
>  .Nm ssh-keygen
>  .Fl K
> +.Op Fl a Ar rounds
>  .Op Fl w Ar provider
>  .Nm ssh-keygen
>  .Fl R Ar hostname
> @@ -125,6 +129,7 @@
>  .Op Fl f Ar input_keyfile
>  .Nm ssh-keygen
>  .Fl A
> +.Op Fl a Ar rounds
>  .Op Fl f Ar prefix_path
>  .Nm ssh-keygen
>  .Fl k
> @@ -248,7 +253,9 @@ keys may be converted using this option
>  .Fl p
>  (change passphrase) flag.
>  .Pp
> -After a key is generated, instructions below detail where the keys
> +After a key is generated,
> +.Nm
> +will ask where the keys
>  should be placed to be activated.
>  .Pp
>  The options are as follows:
> Index: ssh-keygen.c
> ===================================================================
> RCS file: /cvs/src/usr.bin/ssh/ssh-keygen.c,v
> retrieving revision 1.413
> diff -u -p -r1.413 ssh-keygen.c
> --- ssh-keygen.c 26 Jun 2020 05:02:03 -0000 1.413
> +++ ssh-keygen.c 13 Jul 2020 20:34:15 -0000
> @@ -3013,15 +3013,15 @@ static void
>  usage(void)
>  {
>   fprintf(stderr,
> -    "usage: ssh-keygen [-q] [-b bits] [-C comment] [-f output_keyfile] [-m format]\n"
> +    "usage: ssh-keygen [-q] [-a rounds] [-b bits] [-C comment] [-f output_keyfile] [-m format]\n"
>      "                  [-t dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa]\n"
>      "                  [-N new_passphrase] [-O option] [-w provider]\n"
> -    "       ssh-keygen -p [-f keyfile] [-m format] [-N new_passphrase]\n"
> +    "       ssh-keygen -p [-a rounds] [-f keyfile] [-m format] [-N new_passphrase]\n"
>      "                   [-P old_passphrase]\n"
>      "       ssh-keygen -i [-f input_keyfile] [-m key_format]\n"
>      "       ssh-keygen -e [-f input_keyfile] [-m key_format]\n"
>      "       ssh-keygen -y [-f input_keyfile]\n"
> -    "       ssh-keygen -c [-C comment] [-f keyfile] [-P passphrase]\n"
> +    "       ssh-keygen -c [-a rounds] [-C comment] [-f keyfile] [-P passphrase]\n"
>      "       ssh-keygen -l [-v] [-E fingerprint_hash] [-f input_keyfile]\n"
>      "       ssh-keygen -B [-f input_keyfile]\n");
>  #ifdef ENABLE_PKCS11
> @@ -3031,7 +3031,7 @@ usage(void)
>   fprintf(stderr,
>      "       ssh-keygen -F hostname [-lv] [-f known_hosts_file]\n"
>      "       ssh-keygen -H [-f known_hosts_file]\n"
> -    "       ssh-keygen -K [-w provider]\n"
> +    "       ssh-keygen -K [-a rounds] [-w provider]\n"
>      "       ssh-keygen -R hostname [-f known_hosts_file]\n"
>      "       ssh-keygen -r hostname [-g] [-f input_keyfile]\n"
>  #ifdef WITH_OPENSSL
> @@ -3042,7 +3042,7 @@ usage(void)
>      "                  [-n principals] [-O option] [-V validity_interval]\n"
>      "                  [-z serial_number] file ...\n"
>      "       ssh-keygen -L [-f input_keyfile]\n"
> -    "       ssh-keygen -A [-f prefix_path]\n"
> +    "       ssh-keygen -A [-a rounds] [-f prefix_path]\n"
>      "       ssh-keygen -k -f krl_file [-u] [-s ca_public] [-z version_number]\n"
>      "                  file ...\n"
>      "       ssh-keygen -Q [-l] -f krl_file [file ...]\n"
>