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