userdb/userdbpw.8.in

   1 '\" t
   2 .\"  <!-- Copyright 1998 - 2007 Double Precision, Inc.  See COPYING for -->
   3 .\"  <!-- distribution information. -->
   4 .\"     Title: userdbpw
   5 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   6 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   7 .\"      Date: 09/08/2017
   8 .\"    Manual: Double Precision, Inc.
   9 .\"    Source: Double Precision, Inc.
  10 .\"  Language: English
  11 .\"
  12 .TH "USERDBPW" "8" "09/08/2017" "Double Precision, Inc." "Double Precision, Inc."
  13 .\" -----------------------------------------------------------------
  14 .\" * Define some portability stuff
  15 .\" -----------------------------------------------------------------
  16 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  17 .\" http://bugs.debian.org/507673
  18 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  19 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  20 .ie \n(.g .ds Aq \(aq
  21 .el       .ds Aq '
  22 .\" -----------------------------------------------------------------
  23 .\" * set default formatting
  24 .\" -----------------------------------------------------------------
  25 .\" disable hyphenation
  26 .nh
  27 .\" disable justification (adjust text to left margin only)
  28 .ad l
  29 .\" -----------------------------------------------------------------
  30 .\" * MAIN CONTENT STARTS HERE *
  31 .\" -----------------------------------------------------------------
  32 .SH "NAME"
  33 userdbpw \- create an encrypted password
  34 .SH "SYNOPSIS"
  35 .HP \w'\fBuserdbpw\fR\fBuserdb\fR\ 'u
  36 \fBuserdbpw\fR [[\-md5] | [\-hmac\-md5] | [\-hmac\-sha1]] |\fBuserdb\fR {\fIname\fR} set {\fIfield\fR}
  37 .SH "DESCRIPTION"
  38 .PP
  39 \fBuserdbpw\fR
  40 enables secure entry of encrypted passwords into
  41 @userdb@\&.
  42 .PP
  43 \fBuserdbpw\fR
  44 reads a single line of text on standard input, encrypts it, and prints the encrypted result to standard output\&.
  45 .PP
  46 If standard input is attached to a terminal device,
  47 \fBuserdbpw\fR
  48 explicitly issues a "Password: " prompt on standard error, and turns off echo while the password is entered\&.
  49 .PP
  50 The
  51 \fB\-md5\fR
  52 option is available on systems that use MD5\-hashed passwords (such as systems that use the current version of the PAM library for authenticating, with MD5 passwords enabled)\&. This option creates an MD5 password hash, instead of using the traditional
  53 \fBcrypt()\fR
  54 function\&.
  55 .PP
  56 \fB\-hmac\-md5\fR
  57 and
  58 \fB\-hmac\-sha1\fR
  59 options are available only if the userdb library is installed by an application that uses a challenge/response authentication mechanism\&.
  60 \fB\-hmac\-md5\fR
  61 creates an intermediate HMAC context using the MD5 hash function\&.
  62 \fB\-hmac\-sha1\fR
  63 uses the SHA1 hash function instead\&. Whether either HMAC function is actually available depends on the actual application that installs the
  64 \fBuserdb\fR
  65 library\&.
  66 .PP
  67 Note that even though the result of HMAC hashing looks like an encrypted password, it\*(Aqs really not\&. HMAC\-based challenge/response authentication mechanisms require the cleartext password to be available as cleartext\&. Computing an intermediate HMAC context does scramble the cleartext password, however if its compromised, it WILL be possible for an attacker to succesfully authenticate\&. Therefore, applications that use challenge/response authentication will store intermediate HMAC contexts in the "pw" fields in the userdb database, which will be compiled into the
  68 userdbshadow\&.dat
  69 database, which has group and world permissions turned off\&. The userdb library also requires that the cleartext userdb source for the
  70 userdb\&.dat
  71 and
  72 userdbshadow\&.dat
  73 databases is also stored with the group and world permissions turned off\&.
  74 .PP
  75 \fBuserdbpw\fR
  76 is usually used together in a pipe with
  77 \fBuserdb\fR, which reads from standard input\&. For example:
  78 .sp
  79 .if n \{\
  80 .RS 4
  81 .\}
  82 .nf
  83 \fBuserdbpw \-md5 | userdb users/john set systempw\fR
  84 .fi
  85 .if n \{\
  86 .RE
  87 .\}
  88 .PP
  89 or:
  90 .sp
  91 .if n \{\
  92 .RS 4
  93 .\}
  94 .nf
  95 \fBuserdbpw \-hmac\-md5 | userdb users/john set hmac\-md5pw\fR
  96 .fi
  97 .if n \{\
  98 .RE
  99 .\}
 100 .PP
 101 These commands set the
 102 \fBsystempw\fR
 103 field in the record for the user
 104 \fBjohn\fR
 105 in
 106 @userdb@/users
 107 file, and the
 108 \fBhmac\-md5pw\fR
 109 field\&. Don\*(Aqt forget to run
 110 \fBmakeuserdb\fR
 111 for the change to take effect\&.
 112 .PP
 113 The following command does the same thing:
 114 .sp
 115 .if n \{\
 116 .RS 4
 117 .\}
 118 .nf
 119 \fBuserdb users/john set systempw=\fR\fB\fBSECRETPASSWORD\fR\fR
 120 .fi
 121 .if n \{\
 122 .RE
 123 .\}
 124 .PP
 125 However, this command passes the secret password as an argument to the
 126 \fBuserdb\fR
 127 command, which can be viewed by anyone who happens to run
 128 \fBps\fR(1)
 129 at the same time\&. Using
 130 \fBuserdbpw\fR
 131 allows the secret password to be specified in a way that cannot be easily viewed by
 132 \fBps\fR(1)\&.
 133 .SH "SEE ALSO"
 134 .PP
 135 \m[blue]\fB\fBuserdb\fR(8)\fR\m[]\&\s-2\u[1]\d\s+2,
 136 \m[blue]\fB\fBmakeuserdb\fR(8)\fR\m[]\&\s-2\u[2]\d\s+2
 137 .SH "NOTES"
 138 .IP " 1." 4
 139 \fBuserdb\fR(8)
 140 .RS 4
 141 \%[set $man.base.url.for.relative.links]/userdb.html
 142 .RE
 143 .IP " 2." 4
 144 \fBmakeuserdb\fR(8)
 145 .RS 4
 146 \%[set $man.base.url.for.relative.links]/makeuserdb.html
 147 .RE