pam_yubico.8

'\" t
.\"     Title: pam_yubico
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: Version 2.22
.\"    Manual: Yubico PAM Module Manual
.\"    Source: yubico-pam
.\"  Language: English
.\"
.TH "PAM_YUBICO" "8" "Version 2\&.22" "yubico\-pam" "Yubico PAM Module 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_yubico \- Module for YubiKey authentication
.SH "SYNOPSIS"
.sp
\fBpam_yubico\fR [\&...]
.SH "DESCRIPTION"
.sp
The module is for authentication of YubiKeys, either with online validation of OTP, or offline validation with HMAC\-SHA1 challenge\-response\&.
.SH "OPTIONS"
.PP
\fBdebug\fR
.RS 4
Turns on debugging to STDOUT
.RE
.PP
\fBmode=\fR[\fIclient\fR|\fIchallenge\-response\fR]
.RS 4
Set the mode of operation, client for OTP validation and challenge\-response for challenge\-response validation, client is the default\&.
.RE
.PP
\fBauthfile\fR=\fIfile\fR
.RS 4
Set the location of the file that holds the mappings of Yubikey token IDs to user names\&. The format is username:first_public_id:second_public_id:\&... default location of the file is $HOME/\&.yubico/authorized_yubikeys\&.
.RE
.PP
\fBid\fR=\fIid\fR
.RS 4
Set to your client identity\&.
.RE
.PP
\fBkey\fR=\fIkey\fR
.RS 4
Set to your client key in base64 format\&. The client key is also known as API key, and provides integrity in the communication between the client (you) and the validation server\&. If you want to get one for use with the default YubiCloud service, please go to
https://upgrade\&.yubico\&.com/getapikey/
.RE
.PP
\fBalwaysok\fR
.RS 4
Set to enable all authentication attempts to succeed (aka presentation mode)\&.
.RE
.PP
\fBtry_first_pass\fR
.RS 4
Before prompting the user for their password, the module first tries the previous stacked module\(aas password in case that satisfies this module as well\&.
.RE
.PP
\fBuse_first_pass\fR
.RS 4
The argument use_first_pass forces the module to use a previous stacked modules password and will never prompt the user \- if no password is available or the password is not appropriate, the user will be denied access\&.
.RE
.PP
\fBurllist\fR=\fIlist\fR
.RS 4
List of URL templates to be used\&. This is set by calling ykclient_set_url_bases\&. The list should be in the format:
https://api1\&.example\&.com/wsapi/2\&.0/verify;https://api2\&.example\&.com/wsapi/2\&.0/verify
.RE
.PP
\fBurl\fR=\fIurl\fR
.RS 4
This option should not be used, please use the urllist option instead\&. Set the URL template to use, this is set by calling ykclient_set_url_template\&. The URL should be set in the format
https://api\&.example\&.com/wsapi/2\&.0/verify?id=%d&otp=%s
.RE
.PP
\fBcapath\fR=\fIpath\fR
.RS 4
Specify the path where X509 certificates are stored\&. This is required if
\fIhttps\fR
or
\fIldaps\fR
are used in
\fIurl\fR
and
\fIldap_uri\fR
respectively\&.
.RE
.PP
\fBproxy\fR=\fIproxy\fR
.RS 4
Specify a proxy to connect to the validation server\&. Valid schemes are socks4://, socks4a://, socks5:// or socks5h://\&. Socks5h asks the proxy to do the dns resolving\&. If no scheme or port is specified HTTP proxy port 1080 will be used\&. E\&.g\&. socks5h://user:pass@10\&.10\&.0\&.1:1080
.RE
.PP
\fBverbose_otp\fR
.RS 4
This argument is used to show the OTP (One Time Password) when it is entered, i\&.e\&. to enable terminal echo of entered characters\&. You are advised to not use this, if you are using two factor authentication because that will display your password on the screen\&. This requires the service using the PAM module to display custom fields\&. This option can not be used with OpenSSH\&.
.RE
.PP
\fBldap_uri\fR=\fIuri\fR
.RS 4
Specify the LDAP server URI (e\&.g\&. ldap://localhost)\&.
.RE
.PP
\fBldap_server\fR=\fIserver\fR
.RS 4
Specify the LDAP server host (default LDAP port is used)\&.
\fBDeprecated\&. Use \fR\fB\fIldap_uri\fR\fR\fB instead\&.\fR
.RE
.PP
\fBldapdn\fR=\fIdn\fR
.RS 4
The dn where the users are stored (eg: ou=users,dc=domain,dc=com)\&. If
\fIldap_filter\fR
is used this is the base from which the subtree search will be performed\&.
.RE
.PP
\fBuser_attr\fR=\fIattr\fR
.RS 4
The LDAP attribute used to store user names (eg:cn)\&.
.RE
.PP
\fByubi_attr\fR=\fIattr\fR
.RS 4
The LDAP attribute used to store the Yubikey id\&.
.RE
.PP
\fByubi_attr_prefix\fR=\fIprefix\fR
.RS 4
The prefix of the LDAP attribute\(cqs value, in case of a generic attribute, used to store several types of ids\&.
.RE
.PP
\fBtoken_id_length\fR=\fIlength\fR
.RS 4
Length of ID prefixing the OTP (this is 12 if using the YubiCloud)\&.
.RE
.PP
\fBldap_bind_user\fR=\fIuser\fR
.RS 4
The user to attempt a LDAP bind as\&.
.RE
.PP
\fBldap_bind_password\fR=\fIpassword\fR
.RS 4
The password to use on LDAP bind\&.
.RE
.PP
\fBldap_filter\fR=\fIfilter\fR
.RS 4
An ldap filter to use for attempting to find the correct object in LDAP\&. In this string %u will be replaced with the username\&.
.RE
.PP
\fBldap_cacertfile\fR=\fIcacertfile\fR
.RS 4
Ca certfile for the LDAP connection\&.
.RE
.PP
\fBchalresp_path\fR=\fIpath\fR
.RS 4
Path of a system wide directory where challenge response files can be found for users\&. Default location is $HOME/\&.yubico/
.RE
.SH "EXAMPLES"
.sp
.if n \{\
.RS 4
.\}
.nf
auth sufficient pam_yubico\&.so id=16 debug
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
auth required pam_yubico\&.so mode=challenge\-response
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
auth required pam_yubico\&.so id=16 ldap_uri=ldaps://ldap\&.example\&.com ldap_filter=(uid=%u) yubi_attr=yubiKeyId
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.PP
\fB$HOME/\&.yubico/authorized_yubikeys\fR
.RS 4
If
\fBauthfile\fR
is not set this file is used for the mapping between YubiKey public id and in
\fIclient\fR
mode\&.
.RE
.PP
\fB$HOME/\&.yubico/challenge\fR, \fB$HOME/\&.yubico/challenge\-\fR\fB\fIserial_number\fR\fR
.RS 4
If
\fBchalresp_path\fR
is not set these files are used to hold next challenge and expected response for the user in
\fIchallenge\-response\fR
mode\&. If
\fBchalresp_path\fR
is set the filename will be username instead of challenge\&.
.RE
.SH "BUGS"
.sp
Report yubico\-pam bugs in the issue tracker: https://github\&.com/Yubico/yubico\-pam/issues
.SH "SEE ALSO"
.sp
\fBykpamcfg\fR(1), \fBpam\fR(7)
.sp
The yubico\-pam home page: https://developers\&.yubico\&.com/yubico\-pam/
.sp
YubiKeys can be obtained from Yubico: http://www\&.yubico\&.com/