peek(1) #93

trinity · 2024-04-17T23:18:25Z

trinity commented

2024-04-17 23:18:25 +00:00

peek(1) is a utility that reads standard input and writes to given outputs without echoing to the terminal. It has a number of features that make safer usage convenient and both the code and the man page are very cleanly written. This tool's utility is obvious in the examples; while shell scripts shouldn't accept secrets, if they were to do so this is a thoughtfully designed utility for that task.

This is imported from my source tree with slight tweaks for this repository. @silt helped review this code when it was first written (four months ago).

mm(1) isn't suited for this task because it doesn't prevent terminal echoing. The shell built-in read doesn't either. The featureset of this utility wouldn't make sense for any other one, either (-1 could be | head -n 1, -e could be | tee /dev/stderr, -n could be | tr -d \\n, -o is a default everywhere, -p is a pipe, and -t doesn't make sense elsewhere).

peek(1) is a utility that reads standard input and writes to given outputs *without* echoing to the terminal. It has a number of features that make safer usage convenient and both the code and the man page are very cleanly written. This tool's utility is obvious in the examples; while shell scripts *shouldn't* accept secrets, if they were to do so this is a thoughtfully designed utility for that task. This is [imported from my source tree](https://git.tebibyte.media/trinity/src/src/branch/main/peek) with slight tweaks for this repository. @silt helped review this code when it was first written (four months ago). mm(1) isn't suited for this task because it doesn't prevent terminal echoing. The shell built-in `read` doesn't either. The featureset of this utility wouldn't make sense for any other one, either (`-1` could be `| head -n 1`, `-e` could be `| tee /dev/stderr`, `-n` could be `| tr -d \\n`, `-o` is a default everywhere, `-p` is a pipe, and `-t` doesn't make sense elsewhere).

trinity added the

enhancement

label 2024-04-17 23:18:25 +00:00

trinity added 1 commit 2024-04-17 23:18:25 +00:00

Import peek(1) from trinity/src 4e5fc680e9

trinity requested review from emma 2024-04-17 23:24:29 +00:00

trinity requested review from silt 2024-04-17 23:24:30 +00:00

emma requested changes 2024-04-18 04:34:15 +00:00

docs/peek.1 Outdated

						
				@ -0,0 +19,4 @@

				.SH DESCRIPTION

				Peek reads input from standard input with terminal echo disabled, which may be

emma commented

2024-04-18 04:30:03 +00:00

Peek reads input from standard input with terminal echo disabled,

Read input from the standard input with terminal echo disabled.

which may be useful to prevent secrets being spied upon by adversaries watching a user's
screen.

Should this be placed in a RATIONALE section?

> Peek reads input from standard input with terminal echo disabled, Read input from the standard input with terminal echo disabled. > which may be useful to prevent secrets being spied upon by adversaries watching a user's screen. Should this be placed in a RATIONALE section?

emma marked this conversation as resolved

docs/peek.1 Outdated

						
				@ -0,0 +45,4 @@

				.B -o

				.RS

				Configures peek to output to standard output.

emma commented

2024-04-18 04:30:36 +00:00

“[...] the standard output”

trinity marked this conversation as resolved

docs/peek.1 Outdated

						
				@ -0,0 +48,4 @@

				Configures peek to output to standard output.

				.RE

				.B -p

emma commented

2024-04-18 04:31:40 +00:00

What is the benefit to this over using a shell pipe?

trinity marked this conversation as resolved

docs/peek.1 Outdated

						
				@ -0,0 +94,4 @@

				.R $ env -i PATH="$PATH" peek -1tp htpasswd -nBi _ | cut -d : -f 2

				.RE

				This is a POSIX sh(1) command line that lets a user blindly write into a text

emma commented

2024-04-18 04:33:35 +00:00

Either:

This is a POSIX shell [...]

or:

This is an sh(1p) [...]

Either: > This is a POSIX shell [...] or: > This is an sh(1p) [...]

trinity marked this conversation as resolved

emma commented

2024-04-18 05:05:21 +00:00

Could this functionality be attained using a combination of existing or hypothetical utilities and shell features? We should consider whether this utility should be necessary for its use case.

trinity added 3 commits 2024-04-18 16:04:33 +00:00

peek(1): remove -p 46b607384a

peek(1): strip down to bare essentials, rewrite man page to match c7739612a7

peek(1): correct grammar c295f531cb

trinity commented

2024-04-18 16:08:04 +00:00

Could this functionality be attained using a combination of existing or hypothetical utilities and shell features? We should consider whether this utility should be necessary for its use case.

Yes, actually. After rethinking it I rewrote the utility to be as simple as possible (and have -t be the default as it should have been). The man page has been updated to match, including incorporating all of your comments which I found to be useful.

> Could this functionality be attained using a combination of existing or hypothetical utilities and shell features? We should consider whether this utility should be necessary for its use case. Yes, actually. After rethinking it I rewrote the utility to be as simple as possible (and have `-t` be the default as it should have been). The man page has been updated to match, including incorporating all of your comments which I found to be useful.

trinity requested review from emma 2024-04-18 16:08:09 +00:00

trinity added 1 commit 2024-04-18 16:15:00 +00:00

peek(1): remove unused variables, clean up some typos 6d3f084d9c

emma changed title from ~~peek(1)~~ to WIP: peek(1)

2024-04-25 01:59:50 +00:00

emma changed title from ~~WIP: peek(1)~~ to peek(1)

2024-04-25 01:59:58 +00:00

emma requested changes 2024-05-24 16:37:03 +00:00

docs/peek.1 Outdated

						
				@ -0,0 +27,4 @@

				.SH DIAGNOSTICS

				Peek prints an error message and exits with the appropriate status from

emma commented

2024-05-24 16:30:44 +00:00

In the event of an error, a debug message will be printed and the program will
exit with the appropriate sysexits.h(3) error code.

For parity with the man pages in the docs branch. For example, see npc.1.

> In the event of an error, a debug message will be printed and the program will exit with the appropriate sysexits.h(3) error code. For parity with the man pages in the `docs` branch. For example, see [`npc.1`](https://git.tebibyte.media/bonsai/coreutils/src/commit/b7f52902b6bde54876b5fd8efafa433e2cf0df9a/docs/npc.1#L44).

emma marked this conversation as resolved

docs/peek.1 Outdated

						
				@ -0,0 +30,4 @@

				Peek prints an error message and exits with the appropriate status from

				sysexits.h(3) if it encounters an unrecoverable error.

				Peek tries to handle the signal SIGINT (^C) to ensure the user's terminal is

emma commented

2024-05-24 16:33:18 +00:00

If it encounters a SIGINT signal (^C), the program will attempt to handle it to ensure the user’s terminal is still usable after premature termination; if the signal can’t be handled, it prints an error message and continues. If the program is interrupted, it exits unsuccessfully and without printing an error message.

emma marked this conversation as resolved

docs/peek.1 Outdated

						
				@ -0,0 +44,4 @@

				.SH BUGS

				This does nothing to prevent others seeing the keyboard being used to input

emma commented

2024-05-24 16:27:14 +00:00

This being in the BUGS section implies that this can be fixed by the program. Therefore, this belongs in a CAVEATS section because it is definitionally a caveat.

emma marked this conversation as resolved

docs/peek.1 Outdated

						
				@ -0,0 +69,4 @@

				This is an sh(1p) command line that lets a user blindly write into a text file,

				only able to see written lines. Some writers have the habit of prematurely

				revising their work and use tools like this to prevent it. It uses mm(1) to

				pipe the output of peek to both the standard error and the regular file

emma commented

2024-05-24 16:36:38 +00:00

It uses mm(1) to pipe the hidden input to both the standard error and the regular file writing.txt.

> It uses mm(1) to pipe the hidden input to both the standard error and the regular file writing.txt.

emma marked this conversation as resolved

emma referenced this pull request

2024-05-24 16:44:30 +00:00

eep(1) #103

emma commented

2024-06-09 06:14:10 +00:00

Here is the sum of the changes I recommend to the peek.1 manpage as a git diff:

diff --git a/docs/peek.1 b/docs/peek.1
index 1c482a2..ec56a8e 100644
--- a/docs/peek.1
+++ b/docs/peek.1
@@ -1,90 +1,111 @@
 .\" Copyright (c) 2023-2024 DTB <trinity@trinity.moe>
+.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
 .\"
 .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
 .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-
-.TH PEEK 1
-
+.\"
+.TH PEEK 1 2024-06-09 "Bonsai Core Utilites 0.13.9"
 .SH NAME
-
 peek \(en read from the standard input, furtively
-
+.\"
 .SH SYNOPSIS
 
 peek
 .RB ( -i )
-
+.\"
 .SH DESCRIPTION
 
-Peek reads input from the standard input with terminal echo disabled.
-
+Read input from the standard input with terminal echo disabled.
+.\"
 .SH OPTIONS
 
-.B -i
-.RS
-Allows input to come from sources other than terminals (i.e. a pipe).
-.RE
-
+.IP \fB-i\fP
+Allows input to come from sources other than terminals (i.e., a pipe).
+.\"
 .SH DIAGNOSTICS
 
-Peek prints an error message and exits with the appropriate status from
-sysexits.h(3) if it encounters an unrecoverable error.
-
-Peek tries to handle the signal SIGINT (^C) to ensure the user's terminal is
-still usable after premature termination; if the signal can't be handled, it
-prints an error message and continues. If peek is interrupted, it exits
-unsuccessfully, without an error message.
+In the event of an error, a debug message will be printed and the program will
+exit with the appropriate
+.BR sysexits.h (3)
+error code.
 
+In order to ensure the user\(cqs terminal is still usable after premature
+termination, the program attempts to handle the SIGINT signal; if it cannot,
+an error message is printed and execution continues. If the program is
+interrupted, it exits unsuccessfully without an error message.
+.\"
 .SH RATIONALE
 
-This tool was originally written to accept passwords in shell scripts, as an
-extremely simple alternative to the GNU Privacy Guard project's pinentry(1).
-Accepting input without showing what is being typed is useful when keying in
-secrets in public settings or places with installed surveillance cameras.
-
-.SH BUGS
+This tool was originally written to accept passwords in shell scripts as an
+extremely simple alternative to the GNU Privacy Guard project\(cqs
+.BR pinentry (1)
+utility.
 
-This does nothing to prevent others seeing the keyboard being used to input
-secrets or mask the sound of typing. Audio or video recordings of typing can be
-used to determine what was input without needing to see the characters appear
-on the screen.
+Accepting input without showing what is being typed is useful when keying in
+secrets in public settings or in places where surveillance cameras are
+installed.
+.\"
+.SH CAVEATS
 
-Accepting secrets in shell scripts is probably not adviseable.
+This program does nothing to prevent others from seeing the key presses inputted
+to a keyboard. It also does not protect against the sound of typing being
+analyzed to determine what was inputted without needing to see screen or
+keyboard.
 
-On systems that support it, the ioctl(2) command TIOCSTI can be used to insert
-characters into the standard input going to peek. This doesn't allow snooping
-but can be used for general mischief.
+Accepting secrets in shell scripts is probably not advisable.
 
+On systems that support it, the
+.BR ioctl (2)
+command TIOCSTI can be used to insert characters into the standard input. This
+doesn't allow snooping but can be used for general mischief.
+.\"
 .SH EXAMPLES
 
-This is an sh(1p) command line that hashes a given password. It uses head(1p)
-to only accept one line of input, xargs(1p) and printf(1p) to strip the
-trailing newline, htpasswd(1) from Apache's utilities to hash the input with
-the bcrypt algorithm, and cut(1p) to print only the resulting hash:
+This is an
+.BR sh (1p)
+command line that hashes a given password. It uses
+.BR head (1p)
+to only accept one line of input,
+.BR xargs (1p)
+and
+.BR printf (1p)
+to strip the trailing newline,
+.BR htpasswd (1) 
+from Apache\(cqs utilities to hash the input with the bcrypt algorithm, and
+.BR cut (1p)
+to print only the resulting hash:
 
 .RS
-.R $ peek | head -n 1 | xargs printf '%s' | htpasswd -nBi _ | cut -d : -f 2
+$ peek | head -n 1 | xargs printf '%s' | htpasswd -nBi _ | cut -d : -f 2
 .RE
 
-This is an sh(1p) command line that lets a user blindly write into a text file,
-only able to see written lines. Some writers have the habit of prematurely
-revising their work and use tools like this to prevent it. It uses mm(1) to
-pipe the output of peek to both the standard error and the regular file
-writing.txt.
+This is an
+.BR sh (1p)
+command line that allows a user to write blindly into a text file but displaying
+only written lines. Some writers have the habit of prematurely revising their 
+work and use tools with functionality similar to this to prevent it. 
+It uses
+.BR mm (1)
+to pipe the output of the program to both the standard error and the regular
+file writing.txt:
 
 .RS
-.R $ echo Input ^D to quit. && peek | mm -eo - >writing.txt
+$ echo Input ^D to quit. && peek | mm -eo - >writing.txt
 .RE
-
+.\"
 .SH AUTHOR
 
-Written by DTB <trinity@trinity.moe>.
-
+Written by DTB
+.MT trinity@trinity.moe
+.ME .
+.\"
 .SH COPYRIGHT
 
-Copyright (c) 2023-2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright \(co 2023-2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/gpl.html>.
-
+.\"
 .SH SEE ALSO
-
-ioctl(2), ioctl_tty(2), read(1), sh(1)
+.BR ioctl (2),
+.BR ioctl_tty (2),
+.BR read (1),
+.BR sh (1)

Here is the sum of the changes I recommend to the `peek.1` manpage as a git diff: ``` diff --git a/docs/peek.1 b/docs/peek.1 index 1c482a2..ec56a8e 100644 --- a/docs/peek.1 +++ b/docs/peek.1 @@ -1,90 +1,111 @@ .\" Copyright (c) 2023-2024 DTB <trinity@trinity.moe> +.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media> .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>. - -.TH PEEK 1 - +.\" +.TH PEEK 1 2024-06-09 "Bonsai Core Utilites 0.13.9" .SH NAME - peek \(en read from the standard input, furtively - +.\" .SH SYNOPSIS peek .RB ( -i ) - +.\" .SH DESCRIPTION -Peek reads input from the standard input with terminal echo disabled. - +Read input from the standard input with terminal echo disabled. +.\" .SH OPTIONS -.B -i -.RS -Allows input to come from sources other than terminals (i.e. a pipe). -.RE - +.IP \fB-i\fP +Allows input to come from sources other than terminals (i.e., a pipe). +.\" .SH DIAGNOSTICS -Peek prints an error message and exits with the appropriate status from -sysexits.h(3) if it encounters an unrecoverable error. - -Peek tries to handle the signal SIGINT (^C) to ensure the user's terminal is -still usable after premature termination; if the signal can't be handled, it -prints an error message and continues. If peek is interrupted, it exits -unsuccessfully, without an error message. +In the event of an error, a debug message will be printed and the program will +exit with the appropriate +.BR sysexits.h (3) +error code. +In order to ensure the user\(cqs terminal is still usable after premature +termination, the program attempts to handle the SIGINT signal; if it cannot, +an error message is printed and execution continues. If the program is +interrupted, it exits unsuccessfully without an error message. +.\" .SH RATIONALE -This tool was originally written to accept passwords in shell scripts, as an -extremely simple alternative to the GNU Privacy Guard project's pinentry(1). -Accepting input without showing what is being typed is useful when keying in -secrets in public settings or places with installed surveillance cameras. - -.SH BUGS +This tool was originally written to accept passwords in shell scripts as an +extremely simple alternative to the GNU Privacy Guard project\(cqs +.BR pinentry (1) +utility. -This does nothing to prevent others seeing the keyboard being used to input -secrets or mask the sound of typing. Audio or video recordings of typing can be -used to determine what was input without needing to see the characters appear -on the screen. +Accepting input without showing what is being typed is useful when keying in +secrets in public settings or in places where surveillance cameras are +installed. +.\" +.SH CAVEATS -Accepting secrets in shell scripts is probably not adviseable. +This program does nothing to prevent others from seeing the key presses inputted +to a keyboard. It also does not protect against the sound of typing being +analyzed to determine what was inputted without needing to see screen or +keyboard. -On systems that support it, the ioctl(2) command TIOCSTI can be used to insert -characters into the standard input going to peek. This doesn't allow snooping -but can be used for general mischief. +Accepting secrets in shell scripts is probably not advisable. +On systems that support it, the +.BR ioctl (2) +command TIOCSTI can be used to insert characters into the standard input. This +doesn't allow snooping but can be used for general mischief. +.\" .SH EXAMPLES -This is an sh(1p) command line that hashes a given password. It uses head(1p) -to only accept one line of input, xargs(1p) and printf(1p) to strip the -trailing newline, htpasswd(1) from Apache's utilities to hash the input with -the bcrypt algorithm, and cut(1p) to print only the resulting hash: +This is an +.BR sh (1p) +command line that hashes a given password. It uses +.BR head (1p) +to only accept one line of input, +.BR xargs (1p) +and +.BR printf (1p) +to strip the trailing newline, +.BR htpasswd (1) +from Apache\(cqs utilities to hash the input with the bcrypt algorithm, and +.BR cut (1p) +to print only the resulting hash: .RS -.R $ peek | head -n 1 | xargs printf '%s' | htpasswd -nBi _ | cut -d : -f 2 +$ peek | head -n 1 | xargs printf '%s' | htpasswd -nBi _ | cut -d : -f 2 .RE -This is an sh(1p) command line that lets a user blindly write into a text file, -only able to see written lines. Some writers have the habit of prematurely -revising their work and use tools like this to prevent it. It uses mm(1) to -pipe the output of peek to both the standard error and the regular file -writing.txt. +This is an +.BR sh (1p) +command line that allows a user to write blindly into a text file but displaying +only written lines. Some writers have the habit of prematurely revising their +work and use tools with functionality similar to this to prevent it. +It uses +.BR mm (1) +to pipe the output of the program to both the standard error and the regular +file writing.txt: .RS -.R $ echo Input ^D to quit. && peek | mm -eo - >writing.txt +$ echo Input ^D to quit. && peek | mm -eo - >writing.txt .RE - +.\" .SH AUTHOR -Written by DTB <trinity@trinity.moe>. - +Written by DTB +.MT trinity@trinity.moe +.ME . +.\" .SH COPYRIGHT -Copyright (c) 2023-2024 DTB. License AGPLv3+: GNU AGPL version 3 or later +Copyright \(co 2023-2024 DTB. License AGPLv3+: GNU AGPL version 3 or later <https://gnu.org/licenses/gpl.html>. - +.\" .SH SEE ALSO - -ioctl(2), ioctl_tty(2), read(1), sh(1) +.BR ioctl (2), +.BR ioctl_tty (2), +.BR read (1), +.BR sh (1) ```

trinity commented

2024-06-09 16:52:20 +00:00

Could "inputted" be "input"? Otherwise I like these changes and you may merge them into the peek branch, or I can myself when I'm at keyboard.

emma added 1 commit 2024-06-18 04:29:45 +00:00

peek.1: updates to be more consistent with current documentation 3db83fd79c

silt reviewed 2024-06-18 04:43:04 +00:00

docs/peek.1 Outdated

						
				@ -0,0 +20,4 @@

				.SH OPTIONS

				.IP \fB-i\fP

				Allows input to come from sources other than terminals (i.e., a pipe).

silt commented

2024-06-18 04:43:04 +00:00

This appears to imply that there exists a multitude of other possible sources, but it's not made clear what those are or how to make use of them. Does it support reading input from… files? TCP sockets? IRC messages??

trinity commented

2024-06-26 15:37:45 +00:00

The "i.e." stands for "id est" and can be read as "in other words". Perhaps I should use the English. I mean to say that the source other than a terminal, in this case, is a pipe.

trinity commented

2024-06-26 15:57:33 +00:00

Changed to (pipes) which I think is more clear.

emma commented

2024-06-18 04:46:17 +00:00

I’m still not convinced that this should be a tool instead of a shell feature, like some sort of set analogue that lets you disable echoing.

I’m still not convinced that this should be a tool instead of a shell feature, like some sort of `set` analogue that lets you disable echoing.

trinity commented

2024-06-26 15:34:37 +00:00

I’m still not convinced that this should be a tool instead of a shell feature, like some sort of set analogue that lets you disable echoing.

It's about the fundamentals.

This feature will be available in whatever shell the user wants.
Keeping this functionality in a separate program will make it easier to debug it separately.
No functionality is lost by making this a separate program.

A program should do one thing well. peek(1) does one thing well. Mixing its functionality into another program is unnecessary, makes it generally less valuable, and makes the other program more complex.

> I’m still not convinced that this should be a tool instead of a shell feature, like some sort of `set` analogue that lets you disable echoing. It's about the fundamentals. - This feature will be available in whatever shell the user wants. - Keeping this functionality in a separate program will make it easier to debug it separately. - No functionality is lost by making this a separate program. A program should do one thing well. peek(1) does one thing well. Mixing its functionality into another program is unnecessary, makes it generally less valuable, and makes the other program more complex.

trinity added 1 commit 2024-06-26 15:43:15 +00:00

Merge branch 'main' into peek 262b3c18fb

trinity added 1 commit 2024-06-26 15:46:38 +00:00

Makefile: all: add peek ff993eebdc

trinity added 1 commit 2024-06-26 15:55:45 +00:00

peek.1: fix wording on -i 70ee886b83

trinity commented

2024-06-26 15:56:51 +00:00

My git client was misconfigured; I've signed a child commit to endorse the previous commits, but let me know if there's anything else I should do.

emma commented

2024-06-26 19:49:04 +00:00

My git client was misconfigured; I've signed a child commit to endorse the previous commits, but let me know if there's anything else I should do.

You’re good, the merge commit will be signed anyway

> My git client was misconfigured; I've signed a child commit to endorse the previous commits, but let me know if there's anything else I should do. You’re good, the merge commit will be signed anyway

emma commented

2024-06-26 19:49:35 +00:00

I’m still not convinced that this should be a tool instead of a shell feature, like some sort of set analogue that lets you disable echoing.

It's about the fundamentals.

This feature will be available in whatever shell the user wants.

Keeping this functionality in a separate program will make it easier to debug it separately.

No functionality is lost by making this a separate program.

A program should do one thing well. peek(1) does one thing well. Mixing its functionality into another program is unnecessary, makes it generally less valuable, and makes the other program more complex.

After some thought, I agree with this.

> > I’m still not convinced that this should be a tool instead of a shell feature, like some sort of `set` analogue that lets you disable echoing. > > It's about the fundamentals. > > - This feature will be available in whatever shell the user wants. > - Keeping this functionality in a separate program will make it easier to debug it separately. > - No functionality is lost by making this a separate program. > > A program should do one thing well. peek(1) does one thing well. Mixing its functionality into another program is unnecessary, makes it generally less valuable, and makes the other program more complex. After some thought, I agree with this.

emma reviewed 2024-06-26 23:03:05 +00:00

docs/peek.1 Outdated

						
				@ -0,0 +4,4 @@

				.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,

				.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.

				.\"

				.TH PEEK 1 2024-06-09 "Bonsai Core Utilites 0.13.9"