Convert the project to use the GNU Build System (aka Autotools)

LICENSE was renamed COPYING because otherwise `autoreconf` complains loudly. This is also the reason AUTHORS, INSTALL, and README were created. Man pages were moved into src/pam_panic/man and src/pam_panic_pw/man. Finally, certain variables are passed through the config.h file to the module rather than as -D flags on the command-line.
2018-04-02 14:34:43 -04:00
parent c7e74b6769
commit 05d8fe5d5f
32 changed files with 507 additions and 95 deletions
--- a/src/pam_panic/man/man8/pam_panic.8
+++ b/src/pam_panic/man/man8/pam_panic.8
@ -0,0 +1,197 @@
+'\" t
+.\"     Title: pam_panic
+.\"    Author: [see the "AUTHORS" section]
+.\"      Date: 2018-03-26
+.\"    Manual: Linux-PAM Panic Manual
+.\"    Source: Linux-PAM Panic Manual
+.\"  Language: English
+.\"
+.TH "PAM_PANIC" "8" "2018-03-26" "PAM Panic Manual" "PAM Panic Manual"
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+
+
+.SH "NAME"
+pam_panic \- PAM module with panic function to protect sensitive data in emergency situations
+
+
+.SH "SYNOPSIS"
+.HP \w'\fBpam_panic\&.so\fR\ 'u
+\fBpam_panic\&.so\fR [password] [allow=\fIUUID(GPT)\fR] [reject=\fIUUID(GPT)\fR] [reboot] [poweroff] [serious=\fIUUID\fR]
+
+
+.SH "DESCRIPTION"
+.PP
+The pam_panic PAM module protects sensitive data and provides a panic function for emergency situations\&.
+.PP
+There are two possible options in how to use this PAM module:
+.PD 0
+.PP
+First possible option:
+.RS 2
+There are two removable media which work as keys: the auth key and the panic key\&. 
+The auth key will let you pass to the password prompt whereas the panic key will call the panic function\&.
+.RE
+Second possible option:
+.RS 2
+There are two passwords: the key password and the panic password\&. The key password will let you pass to the original password prompt whereas the panic password will call the panic function\&.
+.RE
+
+.PD 1
+.PP
+The panic function:
+.RS 2
+The behaviour of this function is defined through the arguments \fBreboot\fR, \fBpoweroff\fR and/or \fBserious\fR\&. See the \fBOPTIONS\R section for details\&.
+.RE
+
+
+.SH "OPTIONS"
+.PP
+\fBpassword\fR
+.RS 4
+Activates the password function having a panic and key password\&.
+If the options \fBallow\fR and \fBreject\fR are provided this option will be ignored\&.
+.PD 0
+.PP
+These passwords can be set with the \fBpam_panic_pw\fR(1) command\&.
+.RE
+.PD 1
+.PP
+
+\fBallow=\fR\fB\fIUUID(GPT)\fR\fR
+.RS 4
+The UUID of the device to be used for authentication (the auth key)\&.
+.PD 0
+.PP
+.PD 1
+The device must be GPT-formatted and contain at least one partition\&.
+The UUID of a GPT-formatted device looks like "12345678-9ABC-DEF0-1234-56789ABCDEF0"\&. 
+.PP
+See \fBHOW TO DETERMINE MY UUIDS\fR for details\&.
+.RE
+.PP
+
+\fBreject=\fR\fB\fIUUID(GPT)\fR\fR
+.RS 4
+The UUID of the device to be used in emergencies. The presence of this device will trigger \fBreboot\fR, \fBpoweroff\fR and/or the panic function, depending on whether \fBreboot\fR, \fBpoweroff\fR, and/or \fBserious\fR are specified.
+.PD 0
+.PP
+.PD 1
+The device must be GPT-formatted and contain at least one partition\&.
+The UUID of a GPT-formatted device looks like "12345678-9ABC-DEF0-1234-56789ABCDEF0"\&. 
+.PP
+See \fBHOW TO DETERMINE MY UUIDS\fR for details\&.
+.RE
+.PP
+
+\fBreboot\fR (recommended)
+.RS 4
+Indicates that the system should reboot upon encountering the device specified with \fBreject\fR\&.
+.PP
+If \fBpoweroff\fR is also specified, \fBreboot\fR will be ignored\&.
+.RE
+.PP
+
+\fBpoweroff\fR
+.RS 4
+Indicates that the system should shut down upon encountering the device specified with \fBreject\fR\&.
+This option is discouraged for security reasons\&.
+.RE
+.PP
+
+\fBserious=\fR\fB\fIUUID\fR\fR
+.RS 4
+The UUID of the device containing the LUKS header to erase upon encountering the device specified with \fBreject\fR\&.
+Erasing the LUKS header will render the data unreadable\&.
+.PP
+NOTE: You should make a backup of the LUKS header before using this function\&.
+.RE
+.PP
+
+
+.SH "USAGE"
+.PP
+To activate the module you have to configure PAM\&. See \fBpam\&.conf(5)\fR for details\&.
+.PP
+In general, you will want to add the following to the top of a PAM configuration file:
+.PD 0
+.RS 4
+auth       requisite    pam_panic\&.so auth=<UUID> reject=<UUID> reboot serious=<UUID>
+.PP
+account    requisite    pam_panic\&.so
+.RE
+Or: 
+.RS 4
+auth       requisite    pam_panic.so password reboot serious=<UUID>
+.PP
+account    requisite    pam_panic.so
+.RE
+.PD 1
+
+
+.SH "HOW TO DETERMINE MY UUIDS"
+.PP
+You will find your UUIDs in \fI/dev/disk/by-partuuid\fR\&.
+You might want to execute "\fBls -l /dev/disk/by-partuuid/\fR" in your favourite shell to find out which UUID is which device\&.
+
+
+.SH "RETURN VALUES"
+.PP
+PAM_SUCCESS
+.RS 4
+Access was granted\&.
+.RE
+.PP
+PAM_IGNORE
+.RS 4
+An error has occured\&. The module will be ignored.\&.
+.RE
+.PP
+PAM_MAXTRIES
+.RS 4
+The removable media was not detected\&.
+.RE
+
+
+.SH "FILES"
+.PP
+/lib/*/security/pam_panic\&.so
+.RS 4
+This PAM module\&.
+.RE
+.PP
+/usr/local/bin/pam_panic_pw
+.RS 4
+Program to set and change the passwords\&.
+.RE
+
+
+.SH "BUGS"
+.PP
+Please report bugs and send pull requests to <https://github\&.com/pampanic/pam_panic>\&.
+
+
+.SH "SEE ALSO"
+.PP
+\fBpam_panic_pw\fR(1),
+\fBcryptsetup\fR(8),
+\fBpam\fR(8),
+\fBpam\&.conf\fR(5)
+
+
+.SH "AUTHORS"
+.PD 0
+.PP
+pam_panic was written by Bandie <bandie@chaospott\&.de>\&.
+.PP
+This man page has been revised by Jordy Dickinson <jordy\&.dickinson@icloud\&.com>