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