'\" te
.\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
.TH pam_dhkeys 5 "14 Jun 2011" "SunOS 5.11" "Standards, Environments, and Macros"
.SH NAME
pam_dhkeys \- authentication Diffie-Hellman keys management module
.SH SYNOPSIS
.LP
.nf
\fBpam_dhkeys.so.1\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpam_dhkeys.so.1\fR service module provides functionality to two \fBPAM\fR services: Secure \fBRPC\fR authentication and Secure \fBRPC\fR authentication token management.
.sp
.LP
Secure RPC authentication differs from regular Unix authentication because \fBONC RPC\fRs use Secure RPC as the underlying security mechanism.
.sp
.LP
The following options may be passed to the module:
.sp
.ne 2
.mk
.na
\fBdebug\fR
.ad
.RS 10n
.rt  
\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level
.RE

.sp
.ne 2
.mk
.na
\fBnowarn\fR
.ad
.RS 10n
.rt  
Turn off warning messages
.RE

.SS "Authentication Services"
.sp
.LP
If the user has Diffie-Hellman keys, \fBpam_sm_authenticate()\fR establishes secret keys for the user specified by the \fBPAM_USER\fR (equivalent to running \fBkeylogin\fR(1)), using the authentication token found in the \fBPAM_AUTHTOK\fR item. If \fBpam_sm_setcred()\fR is called with \fBPAM_ESTABLISH_CRED\fR and the user's secure \fBRPC\fR credentials need to be established, these credentials are set. This is equivalent to running \fBkeylogin\fR(1). 
.sp
.LP
If the credentials could not be set and \fBPAM_SILENT\fR is not specified, a diagnostic message is displayed. If \fBpam_setcred()\fR is called with \fBPAM_DELETE_CRED\fR, the user's secure \fBRPC\fR credentials are unset. This is equivalent to running \fBkeylogout\fR(1). 
.sp
.LP
\fBPAM_REINITIALIZE_CRED\fR and \fBPAM_REFRESH_CRED\fR are not supported and return \fBPAM_IGNORE\fR. 
.SS "Authentication Token Management"
.sp
.LP
The \fBpam_sm_chauthtok()\fR implementation checks whether the old login password decrypts the users secret keys. If it doesn't this module prompts the user for an old Secure \fBRPC\fR password and stores it in a pam data item called \fBSUNW_OLDRPCPASS\fR. This data item can be used by the store module to effectively update the users secret keys.
.SH ERRORS
.sp
.LP
The authentication service returns the following error codes:
.sp
.ne 2
.mk
.na
\fB\fBPAM_SUCCESS\fR\fR
.ad
.RS 20n
.rt  
Credentials set successfully.
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_IGNORE\fR\fR
.ad
.RS 20n
.rt  
Credentials not needed to access the password repository.
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_USER_UNKNOWN\fR\fR
.ad
.RS 20n
.rt  
\fBPAM_USER\fR is not set, or the user is unknown.
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_AUTH_ERR\fR\fR
.ad
.RS 20n
.rt  
No secret keys were set. \fBPAM_AUTHTOK\fR is not set, no credentials are present or there is a wrong password.
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_BUF_ERR\fR\fR
.ad
.RS 20n
.rt  
Module ran out of memory.
.RE

.sp
.LP
The authentication token management returns the following error codes:
.sp
.ne 2
.mk
.na
\fB\fBPAM_SUCCESS\fR\fR
.ad
.RS 20n
.rt  
Old \fBrpc\fR password is set in \fBSUNW_OLDRPCPASS\fR
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_USER_UNKNOWN\fR\fR
.ad
.RS 20n
.rt  
User in \fBPAM_USER\fR is unknown.
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_AUTHTOK_ERR\fR\fR
.ad
.RS 20n
.rt  
User did not provide a password that decrypts the secret keys.
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_BUF_ERR\fR\fR
.ad
.RS 20n
.rt  
Module ran out of memory.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT LevelMT-Safe with exceptions
.TE

.SH SEE ALSO
.sp
.LP
\fBkeylogin\fR(1), \fBkeylogout\fR(1), \fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBpam_chauthtok\fR(3PAM), \fBpam_setcred\fR(3PAM), \fBpam_get_item\fR(3PAM), \fBpam_set_data\fR(3PAM), \fBpam_get_data\fR(3PAM), \fBsyslog\fR(3C), \fBlibpam\fR(3LIB), \fBpam.conf\fR(4), \fBattributes\fR(5), \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), \fBpam_unix_session\fR(5)
.SH NOTES
.sp
.LP
The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the multi-threaded application uses its own PAM handle.