1.\" Copyright (c) 2011-2018 Devin Teske 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd June 24, 2018 28.Dt CHECK-PASSWORD.4TH 8 29.Os 30.Sh NAME 31.Nm check-password.4th 32.Nd FreeBSD password-checking boot module 33.Sh DESCRIPTION 34The file that goes by the name of 35.Nm 36is a set of commands designed to do one or more of the following: 37.Pp 38.Dl o Prevent booting without password 39.Dl o Prevent modification of boot options without password 40.Dl o Provide a password to mount geli(8) encrypted root disk(s) 41.Pp 42The commands of 43.Nm 44by themselves are not enough for most uses. 45Please refer to the 46examples below for the most common situations, and to 47.Xr loader 8 48for additional commands. 49.Pp 50Before using any of the commands provided in 51.Nm , 52it must be included 53through the command: 54.Pp 55.Dl include check-password.4th 56.Pp 57This line is present in 58.Pa /boot/loader.4th 59file, so it is not needed (and should not be re-issued) in a normal setup. 60.Pp 61The commands provided by it are: 62.Pp 63.Bl -tag -width disable-module_module -compact -offset indent 64.It Ic check-password 65Multi-purpose function that can protect the interactive boot menu, 66prevent boot without password, or prompt for geli(8) passphrase 67.Pq depending on Xr loader.conf 5 settings . 68.Pp 69First checks 70.Va bootlock_password 71and if-set, the user cannot continue until the correct password is entered. 72.Pp 73Next, checks 74.Va geom_eli_passphrase_prompt 75and if set to 76.Li YES 77.Pq case-insensitive 78prompts the user to enter their GELI password for later mounting of the root 79device(s) during boot. 80.Pp 81Last, checks 82.Va password 83and if-set, tries to 84.Ic autoboot 85and only prompts for password on failure or user-interrupt. 86See 87.Xr loader.conf 5 88for additional information. 89.El 90.Pp 91The environment variables that effect its behavior are: 92.Bl -tag -width bootlock_password -offset indent 93.It Va bootlock_password 94Sets the bootlock password (up to 255 characters long) that is required by 95.Ic check-password 96to be entered before the system is allowed to boot. 97.It Va geom_eli_passphrase_prompt 98Selects whether loader(8) will prompt for GELI credentials, handing-off to the 99kernel for later mounting of 100.Xr geli 8 101encrypted root device(s). 102.It Va password 103Sets the password (up to 255 characters long) that is required by 104.Ic check-password 105before the user is allowed to visit the boot menu. 106.El 107.Sh FILES 108.Bl -tag -width /boot/check-password.4th -compact 109.It Pa /boot/loader 110The 111.Xr loader 8 . 112.It Pa /boot/check-password.4th 113.Nm 114itself. 115.It Pa /boot/loader.rc 116.Xr loader 8 117bootstrapping script. 118.El 119.Sh EXAMPLES 120Standard i386 121.Pa /boot/loader.rc : 122.Pp 123.Bd -literal -offset indent -compact 124include /boot/loader.4th 125check-password 126.Ed 127.Pp 128Set a password in 129.Xr loader.conf 5 130to prevent modification of boot options: 131.Pp 132.Bd -literal -offset indent -compact 133password="abc123" 134.Ed 135.Pp 136Set a password in 137.Xr loader.conf 5 138to prevent booting without password: 139.Pp 140.Bd -literal -offset indent -compact 141bootlock_password="boot" 142.Ed 143.Pp 144Add the following to 145.Xr loader.conf 5 146to generate a prompt at boot to collect GELI credentials for mounting 147.Xr geli 8 148encrypted root device(s): 149.Pp 150.Bd -literal -offset indent -compact 151geom_eli_passphrase_prompt="YES" 152.Ed 153.Sh SEE ALSO 154.Xr loader.conf 5 , 155.Xr loader 8 , 156.Xr loader.4th 8 157.Sh HISTORY 158The 159.Nm 160set of commands first appeared in 161.Fx 9.0 . 162.Sh AUTHORS 163The 164.Nm 165set of commands was written by 166.An -nosplit 167.An Devin Teske Aq dteske@FreeBSD.org . 168