Re: SSH_ASKPASS manpage clarification
Hi, Couple of comments inline. On Sun, Jul 21, 2013 at 03:16:28AM +0200, Alexander Hall wrote: This is an attempt to make the ssh-* man pages more exact regarding SSH_ASKPASS, when used for ssh-agent key confirmation. The point I'm making is that the relevant SSH_ASKPASS environment variable is not that of ssh-add(1) (apart from when ssh-add is actually asking for a passphrase). On a sidenote, I think I'd prefer a 'SSH_CONFIRM' variable or somesuch (falling back to SSH_ASKPASS), but maybe we don't want to pollute the environment any further. /Alexander Index: ssh-add.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-add.1,v retrieving revision 1.58 diff -u -p -r1.58 ssh-add.1 --- ssh-add.1 3 Dec 2012 08:33:02 - 1.58 +++ ssh-add.1 21 Jul 2013 01:09:49 - @@ -84,14 +84,10 @@ to work. The options are as follows: .Bl -tag -width Ds .It Fl c -Indicates that added identities should be subject to confirmation before +Indicates that +.Xr ssh-agent 1 +should ask for confirmation before added identities are being used for authentication. ^ Zap being from above. -Confirmation is performed by the -.Ev SSH_ASKPASS -program mentioned below. -Successful confirmation is signaled by a zero exit status from the -.Ev SSH_ASKPASS -program, rather than text entered into the requester. .It Fl D Deletes all identities from the agent. .It Fl d Index: ssh-agent.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-agent.1,v retrieving revision 1.53 diff -u -p -r1.53 ssh-agent.1 --- ssh-agent.1 21 Nov 2010 01:01:13 - 1.53 +++ ssh-agent.1 21 Jul 2013 01:09:49 - @@ -161,6 +161,18 @@ Later .Xr ssh 1 looks at these variables and uses them to establish a connection to the agent. .Pp +If confirmation before using a key is requested by +.Xr ssh-add 1 , +it is performed by the program specified in the +.Ev SSH_ASKPASS +environment variable, or +.Xr ssh-askpass 1 +if +.Ev SSH_ASKPASS +is not set. +Successful confirmation is signaled by a zero exit status, and that the Maybe drop the that from above. +first line of the program's output is empty or the string yes. +.Pp However, the sentence still reads awkwardly. Are you trying to say the requirement is: if (an_exit_status == 0 (output_string == || output_string == yes)) If so, maybe a better wording would be: Successful confirmation is signaled by a zero exit status, and the first line of the program's output SHOULD be either empty or the string yes. --patrick The agent will never send a private key over its request channel. Instead, operations that require a private key will be performed by the agent, and the result will be returned to the requester. Index: ssh_config.5 === RCS file: /cvs/src/usr.bin/ssh/ssh_config.5,v retrieving revision 1.166 diff -u -p -r1.166 ssh_config.5 --- ssh_config.5 27 Jun 2013 14:05:37 - 1.166 +++ ssh_config.5 21 Jul 2013 01:09:49 - @@ -286,7 +286,7 @@ will cause ssh to listen for control connections, but require confirmation using the .Ev SSH_ASKPASS program before they are accepted (see -.Xr ssh-add 1 +.Xr ssh-agent 1 for details). If the .Cm ControlPath
Re: SSH_ASKPASS manpage clarification
On 07/21/13 08:11, patrick keshishian wrote: Hi, Couple of comments inline. On Sun, Jul 21, 2013 at 03:16:28AM +0200, Alexander Hall wrote: This is an attempt to make the ssh-* man pages more exact regarding SSH_ASKPASS, when used for ssh-agent key confirmation. The point I'm making is that the relevant SSH_ASKPASS environment variable is not that of ssh-add(1) (apart from when ssh-add is actually asking for a passphrase). On a sidenote, I think I'd prefer a 'SSH_CONFIRM' variable or somesuch (falling back to SSH_ASKPASS), but maybe we don't want to pollute the environment any further. /Alexander Index: ssh-add.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-add.1,v retrieving revision 1.58 diff -u -p -r1.58 ssh-add.1 --- ssh-add.13 Dec 2012 08:33:02 - 1.58 +++ ssh-add.121 Jul 2013 01:09:49 - @@ -84,14 +84,10 @@ to work. The options are as follows: .Bl -tag -width Ds .It Fl c -Indicates that added identities should be subject to confirmation before +Indicates that +.Xr ssh-agent 1 +should ask for confirmation before added identities are being used for authentication. ^ Zap being from above. -Confirmation is performed by the -.Ev SSH_ASKPASS -program mentioned below. -Successful confirmation is signaled by a zero exit status from the -.Ev SSH_ASKPASS -program, rather than text entered into the requester. .It Fl D Deletes all identities from the agent. .It Fl d Index: ssh-agent.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-agent.1,v retrieving revision 1.53 diff -u -p -r1.53 ssh-agent.1 --- ssh-agent.1 21 Nov 2010 01:01:13 - 1.53 +++ ssh-agent.1 21 Jul 2013 01:09:49 - @@ -161,6 +161,18 @@ Later .Xr ssh 1 looks at these variables and uses them to establish a connection to the agent. .Pp +If confirmation before using a key is requested by +.Xr ssh-add 1 , +it is performed by the program specified in the +.Ev SSH_ASKPASS +environment variable, or +.Xr ssh-askpass 1 +if +.Ev SSH_ASKPASS +is not set. +Successful confirmation is signaled by a zero exit status, and that the Maybe drop the that from above. +first line of the program's output is empty or the string yes. +.Pp However, the sentence still reads awkwardly. Are you trying to say the requirement is: if (an_exit_status == 0 (output_string == || output_string == yes)) Yup. If so, maybe a better wording would be: Successful confirmation is signaled by a zero exit status, and the first line of the program's output SHOULD be either empty or the string yes. Suggesting the following: Successful confirmation is signaled by a zero exit status, and the first line of the program's output being either empty or the string yes. Must really the full stop should be within the quotes, even though it's not part of the quote? If so, and we may not ignore this for the percieved accuracy of the man pages, I'd suggest we rephrase it so that it is not the last word. /Alexander Index: ssh-add.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-add.1,v retrieving revision 1.58 diff -u -p -r1.58 ssh-add.1 --- ssh-add.1 3 Dec 2012 08:33:02 - 1.58 +++ ssh-add.1 21 Jul 2013 07:14:13 - @@ -84,14 +84,10 @@ to work. The options are as follows: .Bl -tag -width Ds .It Fl c -Indicates that added identities should be subject to confirmation before -being used for authentication. -Confirmation is performed by the -.Ev SSH_ASKPASS -program mentioned below. -Successful confirmation is signaled by a zero exit status from the -.Ev SSH_ASKPASS -program, rather than text entered into the requester. +Indicates that +.Xr ssh-agent 1 +should ask for confirmation before added identities are used for +authentication. .It Fl D Deletes all identities from the agent. .It Fl d Index: ssh-agent.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-agent.1,v retrieving revision 1.53 diff -u -p -r1.53 ssh-agent.1 --- ssh-agent.1 21 Nov 2010 01:01:13 - 1.53 +++ ssh-agent.1 21 Jul 2013 07:14:13 - @@ -161,6 +161,18 @@ Later .Xr ssh 1 looks at these variables and uses them to establish a connection to the agent. .Pp +If confirmation before using a key is requested by +.Xr ssh-add 1 , +it is performed by the program specified in the +.Ev SSH_ASKPASS +environment variable, or +.Xr ssh-askpass 1 +if +.Ev SSH_ASKPASS +is not set. +Successful confirmation is signaled by a zero exit status, and the first line +of the program's output being either empty or the string yes. +.Pp The agent will never send a private key over its request channel.
Re: SSH_ASKPASS manpage clarification
On Sun, Jul 21, 2013 at 09:15:00AM +0200, Alexander Hall wrote: On 07/21/13 08:11, patrick keshishian wrote: Hi, Couple of comments inline. On Sun, Jul 21, 2013 at 03:16:28AM +0200, Alexander Hall wrote: This is an attempt to make the ssh-* man pages more exact regarding SSH_ASKPASS, when used for ssh-agent key confirmation. The point I'm making is that the relevant SSH_ASKPASS environment variable is not that of ssh-add(1) (apart from when ssh-add is actually asking for a passphrase). On a sidenote, I think I'd prefer a 'SSH_CONFIRM' variable or somesuch (falling back to SSH_ASKPASS), but maybe we don't want to pollute the environment any further. /Alexander Index: ssh-add.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-add.1,v retrieving revision 1.58 diff -u -p -r1.58 ssh-add.1 --- ssh-add.1 3 Dec 2012 08:33:02 - 1.58 +++ ssh-add.1 21 Jul 2013 01:09:49 - @@ -84,14 +84,10 @@ to work. The options are as follows: .Bl -tag -width Ds .It Fl c -Indicates that added identities should be subject to confirmation before +Indicates that +.Xr ssh-agent 1 +should ask for confirmation before added identities are being used for authentication. ^ Zap being from above. -Confirmation is performed by the -.Ev SSH_ASKPASS -program mentioned below. -Successful confirmation is signaled by a zero exit status from the -.Ev SSH_ASKPASS -program, rather than text entered into the requester. .It Fl D Deletes all identities from the agent. .It Fl d Index: ssh-agent.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-agent.1,v retrieving revision 1.53 diff -u -p -r1.53 ssh-agent.1 --- ssh-agent.121 Nov 2010 01:01:13 - 1.53 +++ ssh-agent.121 Jul 2013 01:09:49 - @@ -161,6 +161,18 @@ Later .Xr ssh 1 looks at these variables and uses them to establish a connection to the agent. .Pp +If confirmation before using a key is requested by +.Xr ssh-add 1 , +it is performed by the program specified in the +.Ev SSH_ASKPASS +environment variable, or +.Xr ssh-askpass 1 +if +.Ev SSH_ASKPASS +is not set. +Successful confirmation is signaled by a zero exit status, and that the Maybe drop the that from above. +first line of the program's output is empty or the string yes. +.Pp However, the sentence still reads awkwardly. Are you trying to say the requirement is: if (an_exit_status == 0 (output_string == || output_string == yes)) Yup. If so, maybe a better wording would be: Successful confirmation is signaled by a zero exit status, and the first line of the program's output SHOULD be either empty or the string yes. Suggesting the following: Successful confirmation is signaled by a zero exit status, and the first line of the program's output being either empty or the string yes. Must really the full stop should be within the quotes, even though it's not part of the quote? If so, and we may not ignore this for the percieved accuracy of the man pages, I'd suggest we rephrase it so that it is not the last word. I believe so, see: http://owl.english.purdue.edu/owl/resource/577/03/ But, my suggestion mainly was to introduce the word should in order to make the statement less passive, when stating what is expected of the program's first output line. --patrick /Alexander Index: ssh-add.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-add.1,v retrieving revision 1.58 diff -u -p -r1.58 ssh-add.1 --- ssh-add.1 3 Dec 2012 08:33:02 - 1.58 +++ ssh-add.1 21 Jul 2013 07:14:13 - @@ -84,14 +84,10 @@ to work. The options are as follows: .Bl -tag -width Ds .It Fl c -Indicates that added identities should be subject to confirmation before -being used for authentication. -Confirmation is performed by the -.Ev SSH_ASKPASS -program mentioned below. -Successful confirmation is signaled by a zero exit status from the -.Ev SSH_ASKPASS -program, rather than text entered into the requester. +Indicates that +.Xr ssh-agent 1 +should ask for confirmation before added identities are used for +authentication. .It Fl D Deletes all identities from the agent. .It Fl d Index: ssh-agent.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-agent.1,v retrieving revision 1.53 diff -u -p -r1.53 ssh-agent.1 --- ssh-agent.1 21 Nov 2010 01:01:13 - 1.53 +++ ssh-agent.1 21 Jul 2013 07:14:13 - @@ -161,6 +161,18 @@ Later .Xr ssh 1 looks at these variables and uses them to establish a connection to the
Re: SSH_ASKPASS manpage clarification
On 07/21/13 10:07, patrick keshishian wrote: On Sun, Jul 21, 2013 at 09:15:00AM +0200, Alexander Hall wrote: On 07/21/13 08:11, patrick keshishian wrote: However, the sentence still reads awkwardly. Are you trying to say the requirement is: if (an_exit_status == 0 (output_string == || output_string == yes)) Yup. If so, maybe a better wording would be: Successful confirmation is signaled by a zero exit status, and the first line of the program's output SHOULD be either empty or the string yes. Suggesting the following: Successful confirmation is signaled by a zero exit status, and the first line of the program's output being either empty or the string yes. Must really the full stop should be within the quotes, even though it's not part of the quote? If so, and we may not ignore this for the percieved accuracy of the man pages, I'd suggest we rephrase it so that it is not the last word. I believe so, see: http://owl.english.purdue.edu/owl/resource/577/03/ But, my suggestion mainly was to introduce the word should in order to make the statement less passive, when stating what is expected of the program's first output line. Well I'm not all for rfc2119 imperatives in the man pages (and they are rare), but I agree the sentence above is not perfectly clear. I'll drop the comma and reorder a bit: Confirmation is considered affirmative if the exit status is zero and the first line of the program's output is the string yes, or empty. I am however hoping to have jmc@ comment on this, as man pages are not my bikeshed to paint. :-) /Alexander
Re: SSH_ASKPASS manpage clarification
On Sun, Jul 21, 2013 at 09:15:00AM +0200, Alexander Hall wrote: On 07/21/13 08:11, patrick keshishian wrote: If so, maybe a better wording would be: Successful confirmation is signaled by a zero exit status, and the first line of the program's output SHOULD be either empty or the string yes. Suggesting the following: Successful confirmation is signaled by a zero exit status, and the first line of the program's output being either empty or the string yes. Must really the full stop should be within the quotes, even though it's not part of the quote? If so, and we may not ignore this for the percieved accuracy of the man pages, I'd suggest we rephrase it so that it is not the last word. /Alexander the reference patrick sent you is, i presume, a US resource. here's oxford style manual (a uk resource): Except where the matter is quoted for semantic or bibliographic scrutiny, the relationship in British practice between quotation marks and other marks of punctuation is according to the sense. While the rules are somewhat lengthy to state in full, the common-sense approach is to do nothing that changes the meaning of the quotation or renders it confusing to read. In US practice, commas and full points are set inside the closing quotation mark regardless of whether they are part of the quoted material. The resulting ambiguity can cause editorial problems when using material from US sources in British works. regarding: ... yes. for me, it's definitely a case of renders it confusing to read. is the string requested yes. or yes? er, yes? your idea to reword it might be best! note also that your diff introduces a second instance of signaled. there's a few in the ssh code too. and one signalled. that's another uk/us tussle. it's hard to keep things consistent, and not annoy others. regarding your diff... i don't know this stuff well enough to be able to say whether your moving stuff around makes sense, and whether you're moving it to the right place. note, for example, that ssh-agent(1) now documents SSH_ASKPASS, though it does not have an ENVIRONMENT section. and ssh-add(1), which does, and which documents SSH_ASKPASS, does not now directly refer to that environment variable. are you sure, for example, that just changing -c from indicates to indicates that ssh-agent(1) wouldn;t be enough? not saying it would, just asking. but your diff feels incomplete. jmc Index: ssh-add.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-add.1,v retrieving revision 1.58 diff -u -p -r1.58 ssh-add.1 --- ssh-add.1 3 Dec 2012 08:33:02 - 1.58 +++ ssh-add.1 21 Jul 2013 07:14:13 - @@ -84,14 +84,10 @@ to work. The options are as follows: .Bl -tag -width Ds .It Fl c -Indicates that added identities should be subject to confirmation before -being used for authentication. -Confirmation is performed by the -.Ev SSH_ASKPASS -program mentioned below. -Successful confirmation is signaled by a zero exit status from the -.Ev SSH_ASKPASS -program, rather than text entered into the requester. +Indicates that +.Xr ssh-agent 1 +should ask for confirmation before added identities are used for +authentication. .It Fl D Deletes all identities from the agent. .It Fl d Index: ssh-agent.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-agent.1,v retrieving revision 1.53 diff -u -p -r1.53 ssh-agent.1 --- ssh-agent.1 21 Nov 2010 01:01:13 - 1.53 +++ ssh-agent.1 21 Jul 2013 07:14:13 - @@ -161,6 +161,18 @@ Later .Xr ssh 1 looks at these variables and uses them to establish a connection to the agent. .Pp +If confirmation before using a key is requested by +.Xr ssh-add 1 , +it is performed by the program specified in the +.Ev SSH_ASKPASS +environment variable, or +.Xr ssh-askpass 1 +if +.Ev SSH_ASKPASS +is not set. +Successful confirmation is signaled by a zero exit status, and the first line +of the program's output being either empty or the string yes. +.Pp The agent will never send a private key over its request channel. Instead, operations that require a private key will be performed by the agent, and the result will be returned to the requester. Index: ssh_config.5 === RCS file: /cvs/src/usr.bin/ssh/ssh_config.5,v retrieving revision 1.166 diff -u -p -r1.166 ssh_config.5 --- ssh_config.5 27 Jun 2013 14:05:37 - 1.166 +++ ssh_config.5 21 Jul 2013 07:14:13 - @@ -286,7 +286,7 @@ will cause ssh to listen for control connections, but require confirmation using the .Ev SSH_ASKPASS program before they are accepted (see -.Xr ssh-add 1 +.Xr ssh-agent 1 for details). If the
Re: SSH_ASKPASS manpage clarification
On 07/21/13 11:05, Jason McIntyre wrote: On Sun, Jul 21, 2013 at 09:15:00AM +0200, Alexander Hall wrote: On 07/21/13 08:11, patrick keshishian wrote: If so, maybe a better wording would be: Successful confirmation is signaled by a zero exit status, and the first line of the program's output SHOULD be either empty or the string yes. Suggesting the following: Successful confirmation is signaled by a zero exit status, and the first line of the program's output being either empty or the string yes. Must really the full stop should be within the quotes, even though it's not part of the quote? If so, and we may not ignore this for the percieved accuracy of the man pages, I'd suggest we rephrase it so that it is not the last word. /Alexander the reference patrick sent you is, i presume, a US resource. here's oxford style manual (a uk resource): Except where the matter is quoted for semantic or bibliographic scrutiny, the relationship in British practice between quotation marks and other marks of punctuation is according to the sense. While the rules are somewhat lengthy to state in full, the common-sense approach is to do nothing that changes the meaning of the quotation or renders it confusing to read. In US practice, commas and full points are set inside the closing quotation mark regardless of whether they are part of the quoted material. The resulting ambiguity can cause editorial problems when using material from US sources in British works. regarding: ... yes. for me, it's definitely a case of renders it confusing to read. is the string requested yes. or yes? er, yes? your idea to reword it might be best! note also that your diff introduces a second instance of signaled. there's a few in the ssh code too. and one signalled. that's another uk/us tussle. it's hard to keep things consistent, and not annoy others. regarding your diff... i don't know this stuff well enough to be able to say whether your moving stuff around makes sense, and whether you're moving it to the right place. note, for example, that ssh-agent(1) now documents SSH_ASKPASS, though it does not have an ENVIRONMENT section. and ssh-add(1), which does, and which documents SSH_ASKPASS, does not now directly refer to that environment variable. I noticed that about ssh-agent did not have an ENVIRONMENT section, but decided to keep style rather than rewriting the lot. The man pages could probably use a rather thorough overhaul. are you sure, for example, that just changing -c from indicates to indicates that ssh-agent(1) wouldn;t be enough? not saying it would, just asking. but your diff feels incomplete. I don't think so. It would still say Confirmation is performed by the SSH_ASKPASS program mentioned below. which to me implies that it's the environment of ssh-add that is being referred to. /Alexander jmc Index: ssh-add.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-add.1,v retrieving revision 1.58 diff -u -p -r1.58 ssh-add.1 --- ssh-add.1 3 Dec 2012 08:33:02 - 1.58 +++ ssh-add.1 21 Jul 2013 07:14:13 - @@ -84,14 +84,10 @@ to work. The options are as follows: .Bl -tag -width Ds .It Fl c -Indicates that added identities should be subject to confirmation before -being used for authentication. -Confirmation is performed by the -.Ev SSH_ASKPASS -program mentioned below. -Successful confirmation is signaled by a zero exit status from the -.Ev SSH_ASKPASS -program, rather than text entered into the requester. +Indicates that +.Xr ssh-agent 1 +should ask for confirmation before added identities are used for +authentication. .It Fl D Deletes all identities from the agent. .It Fl d Index: ssh-agent.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-agent.1,v retrieving revision 1.53 diff -u -p -r1.53 ssh-agent.1 --- ssh-agent.1 21 Nov 2010 01:01:13 - 1.53 +++ ssh-agent.1 21 Jul 2013 07:14:13 - @@ -161,6 +161,18 @@ Later .Xr ssh 1 looks at these variables and uses them to establish a connection to the agent. .Pp +If confirmation before using a key is requested by +.Xr ssh-add 1 , +it is performed by the program specified in the +.Ev SSH_ASKPASS +environment variable, or +.Xr ssh-askpass 1 +if +.Ev SSH_ASKPASS +is not set. +Successful confirmation is signaled by a zero exit status, and the first line +of the program's output being either empty or the string yes. +.Pp The agent will never send a private key over its request channel. Instead, operations that require a private key will be performed by the agent, and the result will be returned to the requester. Index: ssh_config.5 === RCS file: /cvs/src/usr.bin/ssh/ssh_config.5,v
Re: SSH_ASKPASS manpage clarification
On Sun, Jul 21, 2013 at 10:51:25AM +0200, Alexander Hall wrote: But, my suggestion mainly was to introduce the word should in order to make the statement less passive, when stating what is expected of the program's first output line. Well I'm not all for rfc2119 imperatives in the man pages (and they are rare), but I agree the sentence above is not perfectly clear. I'll drop the comma and reorder a bit: Confirmation is considered affirmative if the exit status is zero and the first line of the program's output is the string yes, or empty. I am however hoping to have jmc@ comment on this, as man pages are not my bikeshed to paint. :-) /Alexander i dislike should because it introduces ambiguity. the text you had originally was perfectly fine. but please, whatever happens, in the name of all that is good, do *not* use Confirmation is considered affirmitive. please! jmc
Re: SSH_ASKPASS manpage clarification
On Sun, Jul 21, 2013 at 11:19:49AM +0200, Alexander Hall wrote: regarding your diff... i don't know this stuff well enough to be able to say whether your moving stuff around makes sense, and whether you're moving it to the right place. note, for example, that ssh-agent(1) now documents SSH_ASKPASS, though it does not have an ENVIRONMENT section. and ssh-add(1), which does, and which documents SSH_ASKPASS, does not now directly refer to that environment variable. I noticed that about ssh-agent did not have an ENVIRONMENT section, but decided to keep style rather than rewriting the lot. The man pages could probably use a rather thorough overhaul. are you sure, for example, that just changing -c from indicates to indicates that ssh-agent(1) wouldn;t be enough? not saying it would, just asking. but your diff feels incomplete. I don't think so. It would still say Confirmation is performed by the SSH_ASKPASS program mentioned below. which to me implies that it's the environment of ssh-add that is being referred to. well, having an ENVIRONMENT section in ssh-add(1) which documents SSH_ASKPASS kind of implies that it's the environment of ssh-add that is being referred to too. i don;t see how you can separate one part, but not the other. jmc
Re: SSH_ASKPASS manpage clarification
On 07/21/13 11:31, Jason McIntyre wrote: On Sun, Jul 21, 2013 at 11:19:49AM +0200, Alexander Hall wrote: regarding your diff... i don't know this stuff well enough to be able to say whether your moving stuff around makes sense, and whether you're moving it to the right place. note, for example, that ssh-agent(1) now documents SSH_ASKPASS, though it does not have an ENVIRONMENT section. and ssh-add(1), which does, and which documents SSH_ASKPASS, does not now directly refer to that environment variable. I noticed that about ssh-agent did not have an ENVIRONMENT section, but decided to keep style rather than rewriting the lot. The man pages could probably use a rather thorough overhaul. are you sure, for example, that just changing -c from indicates to indicates that ssh-agent(1) wouldn;t be enough? not saying it would, just asking. but your diff feels incomplete. I don't think so. It would still say Confirmation is performed by the SSH_ASKPASS program mentioned below. which to me implies that it's the environment of ssh-add that is being referred to. well, having an ENVIRONMENT section in ssh-add(1) which documents SSH_ASKPASS kind of implies that it's the environment of ssh-add that is being referred to too. i don;t see how you can separate one part, but not the other. SSH_ASKPASS in ENVIRONMENT is still relevant and indeed refers to ssh-add's environment, but is merely used for the passphrase, not for subsequent key usage confirmation. The latter is however subject to ssh-agent's environment. My diff removes the SSH_ASKPASS reference in ssh-add(1)'s -c option, since it's actually none of it's business (and adds the Xr for further reading). /Alexander jmc
Re: SSH_ASKPASS manpage clarification
On Sun, Jul 21, 2013 at 11:58:33AM +0200, Alexander Hall wrote: well, having an ENVIRONMENT section in ssh-add(1) which documents SSH_ASKPASS kind of implies that it's the environment of ssh-add that is being referred to too. i don;t see how you can separate one part, but not the other. SSH_ASKPASS in ENVIRONMENT is still relevant and indeed refers to ssh-add's environment, but is merely used for the passphrase, not for subsequent key usage confirmation. The latter is however subject to ssh-agent's environment. My diff removes the SSH_ASKPASS reference in ssh-add(1)'s -c option, since it's actually none of it's business (and adds the Xr for further reading). ok then. as i said, i don;t know this stuff well enough. jmc
SSH_ASKPASS manpage clarification
This is an attempt to make the ssh-* man pages more exact regarding SSH_ASKPASS, when used for ssh-agent key confirmation. The point I'm making is that the relevant SSH_ASKPASS environment variable is not that of ssh-add(1) (apart from when ssh-add is actually asking for a passphrase). On a sidenote, I think I'd prefer a 'SSH_CONFIRM' variable or somesuch (falling back to SSH_ASKPASS), but maybe we don't want to pollute the environment any further. /Alexander Index: ssh-add.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-add.1,v retrieving revision 1.58 diff -u -p -r1.58 ssh-add.1 --- ssh-add.1 3 Dec 2012 08:33:02 - 1.58 +++ ssh-add.1 21 Jul 2013 01:09:49 - @@ -84,14 +84,10 @@ to work. The options are as follows: .Bl -tag -width Ds .It Fl c -Indicates that added identities should be subject to confirmation before +Indicates that +.Xr ssh-agent 1 +should ask for confirmation before added identities are being used for authentication. -Confirmation is performed by the -.Ev SSH_ASKPASS -program mentioned below. -Successful confirmation is signaled by a zero exit status from the -.Ev SSH_ASKPASS -program, rather than text entered into the requester. .It Fl D Deletes all identities from the agent. .It Fl d Index: ssh-agent.1 === RCS file: /cvs/src/usr.bin/ssh/ssh-agent.1,v retrieving revision 1.53 diff -u -p -r1.53 ssh-agent.1 --- ssh-agent.1 21 Nov 2010 01:01:13 - 1.53 +++ ssh-agent.1 21 Jul 2013 01:09:49 - @@ -161,6 +161,18 @@ Later .Xr ssh 1 looks at these variables and uses them to establish a connection to the agent. .Pp +If confirmation before using a key is requested by +.Xr ssh-add 1 , +it is performed by the program specified in the +.Ev SSH_ASKPASS +environment variable, or +.Xr ssh-askpass 1 +if +.Ev SSH_ASKPASS +is not set. +Successful confirmation is signaled by a zero exit status, and that the +first line of the program's output is empty or the string yes. +.Pp The agent will never send a private key over its request channel. Instead, operations that require a private key will be performed by the agent, and the result will be returned to the requester. Index: ssh_config.5 === RCS file: /cvs/src/usr.bin/ssh/ssh_config.5,v retrieving revision 1.166 diff -u -p -r1.166 ssh_config.5 --- ssh_config.527 Jun 2013 14:05:37 - 1.166 +++ ssh_config.521 Jul 2013 01:09:49 - @@ -286,7 +286,7 @@ will cause ssh to listen for control connections, but require confirmation using the .Ev SSH_ASKPASS program before they are accepted (see -.Xr ssh-add 1 +.Xr ssh-agent 1 for details). If the .Cm ControlPath
