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