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 July 02, 2015 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 "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 182initialize the static variable representing the path 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_make 198function creates a properly formatted 199.Bx 200.Xr passwd 5 201line from a 202.Vt struct passwd , 203and returns a pointer to the resulting string. 204The string is allocated with 205.Xr malloc 3 , 206and it is the caller's responsibility to free it with 207.Xr free 3 . 208.Pp 209The 210.Fn pw_make_v7 211function creates a properly formatted 212.Ux V7 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_mkdb 224function regenerates the password database by running 225.Xr pwd_mkdb 8 . 226If 227.Fa user 228only the record corresponding to that user will be updated. 229The 230.Fn pw_mkdb 231function returns 0 in case of success and -1 in case of failure. 232.Pp 233The 234.Fn pw_lock 235function locks the master password file. 236It returns a file descriptor to the master password file on success 237and -1 on failure. 238.Pp 239The 240.Fn pw_scan 241function is a wrapper around the internal libc function 242.Fn __pw_scan . 243It scans the master password file for a line corresponding to the 244.Fa line 245provided and return a 246.Vt struct passwd 247if it matched an existing record. 248In case of failure, it returns 249.Dv NULL . 250Otherwise, it returns a pointer to a 251.Vt struct passwd 252containing the matching record. 253The 254.Vt struct passwd 255is allocated with 256.Xr malloc 3 , 257and it is the caller's responsibility to free it with 258.Xr free 3 . 259.Pp 260The 261.Fn pw_tempname 262function returns the temporary name of the masterfile created via 263.Fn pw_tmp . 264.Pp 265The 266.Fn pw_tmp 267creates and opens a presumably safe temporary password file. 268If 269.Fa mfd 270is a file descriptor to an open password file, it will be read and 271written back to the temporary password file. 272Otherwise if should be set -1. 273The 274.Fn pw_tmp 275returns an open file descriptor to the temporary password file or -1 in case of 276failure. 277.Sh AUTHORS 278Portions of this software were developed for the 279.Fx 280Project by ThinkSec AS and Network Associates Laboratories, the 281Security Research Division of Network Associates, Inc.\& under 282DARPA/SPAWAR contract N66001-01-C-8035 283.Pq Dq CBOSS , 284as part of the DARPA CHATS research program. 285.Pp 286This manual page was written by 287.An Baptiste Daroussin Aq Mt bapt@FreeBSD.org . 288