First commit

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 163 insertions, 0 deletions

diff --git a/key2root.8 b/key2root.8
new file mode 100644
index 0000000..9cb2652
--- /dev/null
+++ b/key2root.8
@@ -0,0 +1,163 @@
+.TH KEY2ROOT 8 key2root
+
+.SH NAME
+key2root - authenticate with a keyfile and run a process as the root user
+
+.SH SYNOPSIS
+.B key2root
+[-k
+.IR key-name ]
+[-e]
+.I command
+.RI [ argument ]\ ...
+
+.SH DESCRIPTION
+The
+.B key2root
+utility takes a keyfile from the standard input and uses it
+to authenticate the user, and if the keyfile is recognised,
+runs the specified
+.I command
+with sanitised and updated environment variables and with
+the keyfile as the standard input.
+
+.SH OPTIONS
+The
+.B key2root
+utility conforms to the Base Definitions volume of POSIX.1-2017,
+.IR "Section 12.2" ,
+.IR "Utility Syntax Guidelines" .
+.PP
+The following option is supported:
+.TP
+.B -e
+Keep the environment variables as is. Neither
+sanitise nor update them.
+.TP
+.BR -k \ \fIkey-name\fP
+Check the input keyfile against a specific known key, rather
+than checking against all known keys.
+
+.SH OPERANDS
+The following operands are supported:
+.TP
+.I command
+The command that shall be run with as the root user.
+This will be both the process image and the process's
+zeroth command line argument.
+.TP
+.IR argument \ ...
+Command line arguments for the command to run.
+
+.SH STDIN
+The
+.B key2root
+utility uses the standard input as the authentication
+key and forwards it to the
+.I command
+it runs upon successful authentication.
+
+.SH INPUT FILES
+None.
+
+.SH ENVIRONMENT VARIABLES
+The following environment variables affects the execution of
+.BR key2root :
+.TP
+.SH PATH
+Default. See to the Base Definitions volume of
+POSIX.1-2017, Section 8.3, Other Environment Variables.
+
+.SH ASYNCHRONOUS EVENTS
+Default.
+
+.SH STDOUT
+The
+.B key2root
+utility does not use the standard output, however the
+.I command
+it starts may.
+
+.SH STDERR
+The standard error is used for diagnostic messages. The
+.I command
+the
+.B key2root
+utility starts may also use the standard error.
+
+.SH OUTPUT FILES
+None.
+
+.SH EXTENDED DESCRIPTION
+None.
+
+.SH EXIT STATUS
+If the
+.B key2root
+utility fails it will exit with one of the following statuses:
+.TP
+124
+Authentication failed.
+.TP
+125
+A error occurred.
+.TP
+126
+The process failed to change process image.
+.TP
+127
+The specified command was not found.
+.PP
+If the
+.B key2root
+utility is successful, the exit status is defined by the
+.I command
+it starts.
+
+.SH CONSEQUENCES OF ERRORS
+Default.
+
+.SH APPLICATION USAGE
+None.
+
+.SH EXAMPLES
+None.
+
+.SH RATIONALE
+.B key2root
+is useful for scripts that require both root access and a
+keyfile: it lets the user write a script that can decrypt
+a keyfile and the successful keyfile decryption to testify
+that the user has authenticated himself rather also requiring
+his password.
+
+.SH NOTES
+The
+.I PATH
+environment variable will not be updated.
+Updates environment variables are:
+.IR HOME ,
+.IR LOGNAME ,
+.IR MAIL ,
+.IR SHEEL ,
+and
+.IR USER .
+
+.SH BUGS
+None.
+
+.SH FUTURE DIRECTIONS
+None.
+
+.SH SEE ALSO
+.BR key2root-addkey (8),
+.BR key2root-lskeys (8),
+.BR key2root-rmkey (8),
+.BR asroot (8),
+.BR sudo (8),
+.BR doas (1),
+.BR su (1)
+
+.SH AUTHORS
+Mattias Andrée
+.RI < maandree@kth.se >