.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. (May have an actual error as the cause.)
.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-crypt (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 < m@maandree.se >