lib/libutil/pw_util.3

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