usr/src/man/man5/pam_authtok_get.5

   1 '\" te
   2 .\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PAM_AUTHTOK_GET 5 "April 9, 2016"
   7 .SH NAME
   8 pam_authtok_get \- authentication and password management module
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBpam_authtok_get.so.1\fR
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .LP
  17 The \fBpam_authtok_get\fR service module provides password prompting
  18 functionality to the PAM stack. It implements \fBpam_sm_authenticate()\fR and
  19 \fBpam_sm_chauthtok()\fR, providing functionality to both the Authentication
  20 Stack and the Password Management Stack.
  21 .SS "Authentication Service"
  22 .LP
  23 The implementation of \fBpam_sm_authenticate\fR(3PAM) prompts the user name if
  24 not set and then tries to get the authentication token from the pam handle. If
  25 the token is not set, it then prompts the user for a password and stores it in
  26 the \fBPAM\fR item \fBPAM_AUTHTOK\fR. This module is meant to be the first
  27 module on an authentication stack where users are to authenticate using a
  28 keyboard.
  29 .SS "Password Management Service"
  30 .LP
  31 Due to the nature of the PAM Password Management stack traversal mechanism, the
  32 \fBpam_sm_chauthtok\fR(3PAM) function is called twice. Once with the
  33 \fBPAM_PRELIM_CHECK\fR flag, and one with the \fBPAM_UPDATE_AUTHTOK\fR flag.
  34 .sp
  35 .LP
  36 In the first (\fBPRELIM\fR) invocation, the implementation of
  37 \fBpam_sm_chauthtok\fR(3PAM) moves the contents of the \fBPAM_AUTHTOK\fR
  38 (current authentication token) to \fBPAM_OLDAUTHTOK\fR, and subsequentially
  39 prompts the user for a new password. This new password is stored in
  40 \fBPAM_AUTHTOK\fR.
  41 .sp
  42 .LP
  43 If a previous module has set \fBPAM_OLDAUTHTOK\fR prior to the invocation of
  44 pam_authtok_get, this module turns into a \fBNO-OP\fR and immediately returns
  45 \fBPAM_SUCCESS\fR.
  46 .sp
  47 .LP
  48 In the second (\fBUPDATE\fR) invocation, the user is prompted to Re-enter his
  49 password. The pam_sm_chauthtok implementation verifies this reentered password
  50 with the password stored in \fBPAM_AUTHTOK\fR. If the passwords match, the
  51 module returns \fBPAM_SUCCESS\fR.
  52 .sp
  53 .LP
  54 The following option can be passed to the module:
  55 .sp
  56 .ne 2
  57 .na
  58 \fBdebug\fR
  59 .ad
  60 .RS 9n
  61 \fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level
  62 .RE
  63
  64 .SH ERRORS
  65 .LP
  66 The authentication service returns the following error codes:
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fBPAM_SUCCESS\fR\fR
  71 .ad
  72 .RS 18n
  73 Successfully obtains authentication token
  74 .RE
  75
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fBPAM_SYSTEM_ERR\fR\fR
  80 .ad
  81 .RS 18n
  82 Fails to retrieve username, username is \fBNULL\fR or empty
  83 .RE
  84
  85 .sp
  86 .LP
  87 The password management service returns the following error codes:
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBPAM_SUCCESS\fR\fR
  92 .ad
  93 .RS 19n
  94 Successfully obtains authentication token
  95 .RE
  96
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBPAM_AUTHTOK_ERR\fR\fR
 101 .ad
 102 .RS 19n
 103 Authentication token manipulation error
 104 .RE
 105
 106 .SH ATTRIBUTES
 107 .LP
 108 See \fBattributes\fR(5) for descriptions of the following attributes:
 109 .sp
 110
 111 .sp
 112 .TS
 113 box;
 114 c | c
 115 l | l .
 116 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 117 _
 118 Interface Stability     Evolving
 119 _
 120 MT Level        MT-Safe with exceptions
 121 .TE
 122
 123 .SH SEE ALSO
 124 .LP
 125 \fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBsyslog\fR(3C),
 126 \fBlibpam\fR(3LIB), \fBpam.conf\fR(4), \fBattributes\fR(5),
 127 \fBpam_authtok_check\fR(5), pam_authtok_get(5), \fBpam_authtok_store\fR(5),
 128 \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5),
 129 \fBpam_unix_auth\fR(5), \fBpam_unix_session\fR(5)
 130 .SH NOTES
 131 .LP
 132 The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the
 133 multi-threaded application uses its own PAM handle.
 134 .sp
 135 .LP
 136 The \fBpam_unix\fR(5) module is no longer supported. Similar functionality is
 137 provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5),
 138 \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5),
 139 \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), and
 140 \fBpam_unix_session\fR(5).