1.\" Copyright (c) 2012 Baptiste Daroussin <bapt@FreeBSD.org> 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 AUTHORS 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 AUTHORS 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 May 10, 2020 28.Dt PW_UTIL 3 29.Os 30.Sh NAME 31.Nm pw_copy , 32.Nm pw_dup , 33.Nm pw_edit , 34.Nm pw_equal , 35.Nm pw_fini , 36.Nm pw_init , 37.Nm pw_make , 38.Nm pw_make_v7 , 39.Nm pw_mkdb , 40.Nm pw_lock , 41.Nm pw_scan , 42.Nm pw_tempname , 43.Nm pw_tmp 44.Nd "functions for passwd file handling" 45.Sh LIBRARY 46.Lb libutil 47.Sh SYNOPSIS 48.In pwd.h 49.In libutil.h 50.Ft int 51.Fn pw_copy "int ffd" "int tfd" "const struct passwd *pw" "struct passwd *oldpw" 52.Ft "struct passwd *" 53.Fn pw_dup "const struct passwd *pw" 54.Ft int 55.Fn pw_edit "int nosetuid" 56.Ft int 57.Fn pw_equal "const struct passwd *pw1" "const struct passwd *pw2" 58.Ft void 59.Fn pw_fini "void" 60.Ft int 61.Fn pw_init "const char *dir" "const char *master" 62.Ft void 63.Fn pw_initpwd "struct passwd *pw" 64.Ft "char *" 65.Fn pw_make "const struct passwd *pw" 66.Ft "char *" 67.Fn pw_make_v7 "const struct passwd *pw" 68.Ft int 69.Fn pw_mkdb "const char *user" 70.Ft int 71.Fn pw_lock "void" 72.Ft "struct passwd *" 73.Fn pw_scan "const char *line" "int flags" 74.Ft "const char *" 75.Fn pw_tempname "void" 76.Ft int 77.Fn pw_tmp "int mfd" 78.Sh DESCRIPTION 79The 80.Fn pw_copy 81function reads a password file from 82.Vt ffd 83and writes it back out to 84.Vt tfd 85possibly with modifications: 86.Bl -dash 87.It 88If 89.Fa pw 90is 91.Dv NULL 92and 93.Fa oldpw 94is not 95.Dv NULL , 96then the record represented by 97.Fa oldpw 98will not be copied (corresponding to user deletion). 99.It 100If 101.Fa pw 102and 103.Fa oldpw 104are not 105.Dv NULL 106then the record corresponding to 107.Fa pw 108will be replaced by the record corresponding to 109.Fa oldpw . 110.It 111If 112.Vt pw 113is set and 114.Vt oldpw 115is 116.Dv NULL 117then the record corresponding to 118.Vt pw 119will be appended (corresponding to user addition). 120.El 121.Pp 122The 123.Fn pw_copy 124function returns -1 in case of failure otherwise 0. 125.Pp 126The 127.Fn pw_dup 128function duplicates the 129.Vt struct passwd 130pointed to by 131.Fa pw 132and returns a pointer to the copy, or 133.Dv NULL 134in case of failure. 135The new 136.Vt struct passwd 137is allocated with 138.Xr malloc 3 , 139and it is the caller's responsibility to free it with 140.Xr free 3 . 141.Pp 142The 143.Fn pw_edit 144function invokes the command specified by the 145.Ev EDITOR 146environment variable (or 147.Pa /usr/bin/vi 148if 149.Ev EDITOR 150is not defined) 151on a temporary copy of the master password file created by 152.Fn pw_tmp . 153If the file was modified, 154.Fn pw_edit 155installs it and regenerates the password database. 156The 157.Fn pw_edit 158function returns -1 in case of failure, 0 if the file was not modified, 159and a non-zero positive number if the file was modified and successfully 160installed. 161.Pp 162The 163.Fn pw_equal 164function compares two 165.Vt struct passwd 166and returns 0 if they are equal. 167.Pp 168The 169.Fn pw_fini 170function destroy the temporary file created by 171.Fn pw_tmp 172if any, 173kills any running instance of 174.Ev EDITOR 175executed by 176.Fn pw_edit 177if any, 178and closes the lock created by 179.Fn pw_lock 180if any. 181.Pp 182The 183.Fn pw_init 184initializes the static variable representing the path to a password file. 185.Fa dir 186is the directory where the password file is located. 187If set to 188.Dv NULL , 189it will default to 190.Pa /etc . 191.Fa master 192is the name of the password file. 193If set to 194.Dv NULL? 195it will default to 196.Pa master.passwd 197.Pp 198The 199.Fn pw_initpwd 200function initializes the 201.Vt passwd 202struct to canonical values. 203The entire structure is zeroed, then 204.Va pw_uid 205and 206.Va pw_gid 207are set to -1, and all string pointers are set to point at 208an internally-defined zero-length string. 209.Pp 210The 211.Fn pw_make 212function creates a properly formatted 213.Bx 214.Xr passwd 5 215line from a 216.Vt struct passwd , 217and returns a pointer to the resulting string. 218The string is allocated with 219.Xr malloc 3 , 220and it is the caller's responsibility to free it with 221.Xr free 3 . 222.Pp 223The 224.Fn pw_make_v7 225function creates a properly formatted 226.Ux V7 227.Xr passwd 5 228line from a 229.Vt struct passwd , 230and returns a pointer to the resulting string. 231The string is allocated with 232.Xr malloc 3 , 233and it is the caller's responsibility to free it with 234.Xr free 3 . 235.Pp 236The 237.Fn pw_mkdb 238function regenerates the password database by running 239.Xr pwd_mkdb 8 . 240If 241.Fa user 242only the record corresponding to that user will be updated. 243The 244.Fn pw_mkdb 245function returns 0 in case of success and -1 in case of failure. 246.Pp 247The 248.Fn pw_lock 249function locks the master password file. 250It returns a file descriptor to the master password file on success 251and -1 on failure. 252.Pp 253The 254.Fn pw_scan 255function is a wrapper around the internal libc function 256.Fn __pw_scan . 257It scans the master password file for a line corresponding to the 258.Fa line 259provided and return a 260.Vt struct passwd 261if it matched an existing record. 262In case of failure, it returns 263.Dv NULL . 264Otherwise, it returns a pointer to a 265.Vt struct passwd 266containing the matching record. 267The 268.Vt struct passwd 269is allocated with 270.Xr malloc 3 , 271and it is the caller's responsibility to free it with 272.Xr free 3 . 273.Pp 274The 275.Fn pw_tempname 276function returns the temporary name of the masterfile created via 277.Fn pw_tmp . 278.Pp 279The 280.Fn pw_tmp 281creates and opens a presumably safe temporary password file. 282If 283.Fa mfd 284is a file descriptor to an open password file, it will be read and 285written back to the temporary password file. 286Otherwise if should be set -1. 287The 288.Fn pw_tmp 289returns an open file descriptor to the temporary password file or -1 in case of 290failure. 291.Sh HISTORY 292The functions for passwd file handling first appeared in 293.Bx 4.4 . 294.Sh AUTHORS 295Portions of this software were developed for the 296.Fx 297Project by ThinkSec AS and Network Associates Laboratories, the 298Security Research Division of Network Associates, Inc.\& under 299DARPA/SPAWAR contract N66001-01-C-8035 300.Pq Dq CBOSS , 301as part of the DARPA CHATS research program. 302.Pp 303This manual page was written by 304.An Baptiste Daroussin Aq Mt bapt@FreeBSD.org . 305