1 files changed, 134 insertions, 0 deletions
diff --git a/doc/man/pam_sm_setcred.3 b/doc/man/pam_sm_setcred.3
new file mode 100644
index 00000000..fbeb9a8f
--- /dev/null
+++ b/doc/man/pam_sm_setcred.3
@@ -0,0 +1,134 @@
+'\" t
+.\"     Title: pam_sm_setcred
+.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\"      Date: 05/18/2017
+.\"    Manual: Linux-PAM Manual
+.\"    Source: Linux-PAM Manual
+.\"  Language: English
+.\"
+.TH "PAM_SM_SETCRED" "3" "05/18/2017" "Linux-PAM Manual" "Linux-PAM Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+pam_sm_setcred \- PAM service function to alter credentials
+.SH "SYNOPSIS"
+.sp
+.ft B
+.nf
+#define PAM_SM_AUTH
+.fi
+.ft
+.sp
+.ft B
+.nf
+#include <security/pam_modules\&.h>
+.fi
+.ft
+.HP \w'int\ pam_sm_setcred('u
+.BI "int pam_sm_setcred(pam_handle_t\ *" "pamh" ", int\ " "flags" ", int\ " "argc" ", const\ char\ **" "argv" ");"
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_sm_setcred\fR
+function is the service module\*(Aqs implementation of the
+\fBpam_setcred\fR(3)
+interface\&.
+.PP
+This function performs the task of altering the credentials of the user with respect to the corresponding authorization scheme\&. Generally, an authentication module may have access to more information about a user than their authentication token\&. This function is used to make such information available to the application\&. It should only be called
+\fIafter\fR
+the user has been authenticated but before a session has been established\&.
+.PP
+Valid flags, which may be logically OR\*(Aqd with
+\fIPAM_SILENT\fR, are:
+.PP
+PAM_SILENT
+.RS 4
+Do not emit any messages\&.
+.RE
+.PP
+PAM_ESTABLISH_CRED
+.RS 4
+Initialize the credentials for the user\&.
+.RE
+.PP
+PAM_DELETE_CRED
+.RS 4
+Delete the credentials associated with the authentication service\&.
+.RE
+.PP
+PAM_REINITIALIZE_CRED
+.RS 4
+Reinitialize the user credentials\&.
+.RE
+.PP
+PAM_REFRESH_CRED
+.RS 4
+Extend the lifetime of the user credentials\&.
+.RE
+.PP
+The way the
+\fBauth\fR
+stack is navigated in order to evaluate the
+\fBpam_setcred\fR() function call, independent of the
+\fBpam_sm_setcred\fR() return codes, is exactly the same way that it was navigated when evaluating the
+\fBpam_authenticate\fR() library call\&. Typically, if a stack entry was ignored in evaluating
+\fBpam_authenticate\fR(), it will be ignored when libpam evaluates the
+\fBpam_setcred\fR() function call\&. Otherwise, the return codes from each module specific
+\fBpam_sm_setcred\fR() call are treated as
+\fBrequired\fR\&.
+.SH "RETURN VALUES"
+.PP
+PAM_CRED_UNAVAIL
+.RS 4
+This module cannot retrieve the user\*(Aqs credentials\&.
+.RE
+.PP
+PAM_CRED_EXPIRED
+.RS 4
+The user\*(Aqs credentials have expired\&.
+.RE
+.PP
+PAM_CRED_ERR
+.RS 4
+This module was unable to set the credentials of the user\&.
+.RE
+.PP
+PAM_SUCCESS
+.RS 4
+The user credential was successfully set\&.
+.RE
+.PP
+PAM_USER_UNKNOWN
+.RS 4
+The user is not known to this authentication module\&.
+.RE
+.PP
+These, non\-\fIPAM_SUCCESS\fR, return values will typically lead to the credential stack
+\fIfailing\fR\&. The first such error will dominate in the return value of
+\fBpam_setcred\fR()\&.
+.SH "SEE ALSO"
+.PP
+\fBpam\fR(3),
+\fBpam_authenticate\fR(3),
+\fBpam_setcred\fR(3),
+\fBpam_sm_authenticate\fR(3),
+\fBpam_strerror\fR(3),
+\fBPAM\fR(8)