'\" t
.\"     Title: pam_yubico
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: Version 2.27
.\"    Manual: Yubico PAM Module Manual
.\"    Source: yubico-pam
.\"  Language: English
.\"
.TH "PAM_YUBICO" "8" "Version 2\&.27" "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\&.
.RE
.PP
\fBdebug_file\fR=\fIfile\fR
.RS 4
File name to write debug to, the file must exist and be a regular file\&. Defaults to stdout\&.
.RE
.PP
\fBmode=\fR[\fIclient\fR|\fIchallenge\-response\fR]
.RS 4
Mode of operation, client for OTP validation and challenge\-response for challenge\-response validation\&. Defaults to client\&.
.RE
.PP
\fBauthfile\fR=\fIfile\fR
.RS 4
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
Your API client identity for the validation server\&.
.RE
.PP
\fBkey\fR=\fIkey\fR
.RS 4
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
Succeed with all authentication attempts (\fBdangerous\fR, 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
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
\fBalways_prompt\fR
.RS 4
If set, don\(cqt attempt to do a lookup to determine if the user has a YubiKey configured but instead prompt for one no matter what\&. This is useful in the case where ldap_bind_as_user is enabled but this module is being used to read the user\(cqs password (in a YubiKey+OTP auth scenario)\&.
.RE
.PP
\fBnullok\fR
.RS 4
Don\(cqt fail when there are no tokens declared for the user in the authorization mapping files or in LDAP\&. This can be used to make YubiKey authentication optional unless the user has associated tokens\&.
.RE
.PP
\fBldap_starttls\fR
.RS 4
If set, issue a STARTTLS command to the LDAP connection before attempting to bind to it\&. This is a common setup for servers that only listen on port 389 but still require TLS\&.
.RE
.PP
\fBldap_bind_as_user\fR
.RS 4
Use the user logging in to bind to ldap\&. This will use the password provided by the user via PAM\&. If this is set, ldapdn and uid_attr must also be set\&. Enabling this will cause ldap_bind_user and ldap_bind_password to be ignored\&.
.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
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
\fBcainfo\fR=\fIfile\fR
.RS 4
Option to allow for usage of a CA bundle instead of path\&.
.RE
.PP
\fBproxy\fR=\fIproxy\fR
.RS 4
The proxy to connect to the validation server\&. Valid schemes are http://, https://, 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\&. Example: socks5h://user:pass@10\&.10\&.0\&.1:1080
.RE
.PP
\fBverbose_otp\fR
.RS 4
Show the 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
The LDAP server URI (e\&.g\&. ldap://localhost)\&.
.RE
.PP
\fBldap_server\fR=\fIserver\fR
.RS 4
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 distinguished name (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
\fBldap_clientcertfile\fR=\fIclientcertfile\fR
.RS 4
The path to a client cert file to use when talking to the LDAP server\&. Note this requires
\fIldap_clientkeyfile\fR
to be set as well\&.
.RE
.PP
\fBldap_clientkeyfile\fR=\fIclientkeyfile\fR
.RS 4
The path to a key to be used with the client cert when talking to the LDAP server\&. Note this requires
\fIldap_clientcertfile\fR
to be set as well\&.
.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
A 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 certitificate file 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
.PP
\fBmysql_server\fR=\fImysqlserver\fR
.RS 4
Hostname/Adress of mysql server\&. Example 10\&.0\&.0\&.1
.RE
.PP
\fBmysql_port\fR=\fImysqlport\fR
.RS 4
Network port of mysql server\&.
.RE
.PP
\fBmysql_user\fR=\fImysqluser\fR
.RS 4
User for accessing to the database\&. Strongly recommended to use a specific user with read only access\&.
.RE
.PP
\fBmysql_password\fR=\fImysqlpassword\fR
.RS 4
Mysql password associated to the user\&.
.RE
.PP
\fBmysql_database\fR=\fImysqldatabase\fR
.RS 4
the name of the database\&. Example : otp
.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
\fIusername\fR
instead of
\fIchallenge\fR\&.
.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/