rooty/yubico-pam
1
0
Fork 0
mirror of https://github.com/Yubico/yubico-pam.git synced 2025-01-19 07:52:23 +01:00
Code Issues Projects Releases Wiki Activity

convert manpages to asciidoc

Browse Source
This commit is contained in:
Klas Lindfors 2014-06-11 13:33:34 +02:00
parent b0c7b7591d
commit 35e9f95118
7 changed files with 179 additions and 244 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@ -39,3 +39,5 @@ ykpamcfg-ykpamcfg.o
test-suite.log
test.log
test.trs
pam_yubico.8
ykpamcfg.1

12
Makefile.am
View File

@ -57,6 +57,7 @@ dist_man1_MANS = ykpamcfg.1
endif
dist_man8_MANS = pam_yubico.8
DISTCLEANFILES = $(dist_man1_MANS) $(dist_man8_MANS)
# Self tests.
@ -66,7 +67,15 @@ LDADD = ./pam_yubico.la
check_PROGRAMS = test
TESTS = $(check_PROGRAMS)
EXTRA_DIST = doc/LocalAuthenticationUsingChallengeResponse.txt doc/MacOSXChallengeResponse.txt doc/TwoFactorPAMConfiguration.txt doc/UbuntuFreeRadiusYubiKey.txt doc/YubiKeyAndFreeRADIUSviaPAM.txt doc/YubiKeyAndFreeRADIUSwithsinglefactorauthenticationviaPAM.txt doc/YubiKeyAndOpenVPNviaPAM.txt doc/YubikeyAndRadiusViaPAM.txt doc/Yubikey-and-SELinux-on-Fedora-18-and-up.txt doc/YubikeyAndSSHViaPAM.txt
MANSOURCES = pam_yubico.8.txt ykpamcfg.1.txt
EXTRA_DIST = doc/LocalAuthenticationUsingChallengeResponse.txt doc/MacOSXChallengeResponse.txt doc/TwoFactorPAMConfiguration.txt doc/UbuntuFreeRadiusYubiKey.txt doc/YubiKeyAndFreeRADIUSviaPAM.txt doc/YubiKeyAndFreeRADIUSwithsinglefactorauthenticationviaPAM.txt doc/YubiKeyAndOpenVPNviaPAM.txt doc/YubikeyAndRadiusViaPAM.txt doc/Yubikey-and-SELinux-on-Fedora-18-and-up.txt doc/YubikeyAndSSHViaPAM.txt $(MANSOURCES)
SUFFIXES = .1.txt .1 .8.txt .8
.1.txt.1:
$(A2X) --format=manpage -a revdate="Version $(VERSION)" $<
.8.txt.8:
$(A2X) --format=manpage -a revdate="Version $(VERSION)" $<
# Release
@ -103,4 +112,5 @@ release:
cd $(srcdir) && git push
cd $(srcdir) && git tag -u $(KEYID) -m $(VERSION) $(VERSION)
cd $(srcdir) && git push --tags
$(YUBICO_GITHUB_REPO)/save-mans $(PROJECT) $(MANSOURCES)
$(YUBICO_GITHUB_REPO)/publish $(PROJECT) $(VERSION) $(PACKAGE)-$(VERSION).tar.gz*

1
configure.ac
View File

@ -38,6 +38,7 @@ m4_ifdef([AM_PROG_AR], [AM_PROG_AR])
AC_LIBTOOL_WIN32_DLL
AC_DISABLE_STATIC
AC_PROG_LIBTOOL
AM_MISSING_PROG([A2X], a2x, $missing_dir)
AC_CHECK_HEADERS([security/pam_appl.h], [],
[AC_MSG_ERROR([[PAM header files not found, install libpam-dev.]])])

121
pam_yubico.8
View File

@ -1,121 +0,0 @@
.\" Copyright (c) 2013-2014 Yubico AB
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\"
.\" * Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\"
.\" * Redistributions in binary form must reproduce the above
.\" copyright notice, this list of conditions and the following
.\" disclaimer in the documentation and/or other materials provided
.\" with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" The following commands are required for all man pages.
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH pam_yubico "8" "October 2013" "yubico-pam"
.SH NAME
pam_yubico - Module for YubiKey authentication
.SH SYNOPSIS
.B pam_yubico
[...]
.SH DESCRIPTION
The module is for authentication of YubiKeys, either with online validation of OTP, or offline validation with HMAC-SHA1 challenge-response.
.SH OPTIONS
.B debug
Turns on debugging to STDOUT
.TP
.B mode=\fR[\fIclient\fR|\fIchallenge-response\fR]
Set the mode of operation, client for OTP validation and challenge-response for challenge-response validation, client is the default.
.TP
.B authfile=\fIfile\fR
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.
.TP
.B id=\fIid\fR
Set to your client identity.
.TP
.B key=\fIkey\fR
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, visit this URL:
.URL https://upgrade.yubico.com/getapikey/
.TP
.B alwaysok
Set to enable all authentication attempts to succeed (aka presentation mode).
.TP
.B try_first_pass
Before prompting the user for their password, the module first tries the previous stacked module´s password in case that satisfies this module as well.
.TP
.B use_first_pass
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.
.TP
.B urllist=\fIlist\fR
List of URL templates to be used. This is set by calling ykclient_set_url_bases.
The list should be in the format
.URL https://api1.example.com/wsapi/2.0/verify;https://api2.example.com/wsapi/2.0/verify
.TP
.B url=\fIurl\fR
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
.URL https://api.example.com/wsapi/2.0/verify?id=%d&otp=%s
.TP
.B capath=\fIpath\fR
Specify the path where X509 certificates are stored. This is required if 'https' or 'ldaps' are used in 'url' and 'ldap_uri' respectively.
.TP
.B verbose_otp
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. For example, OpenSSH requires you to configure "ChallengeResponseAuthentication no".
.TP
.B ldap_uri=\fIuri\fR
Specify the LDAP server URI (e.g. ldap://localhost).
.TP
.B ldap_server=\fIserver\fR
Specify the LDAP server host (default LDAP port is used).
.B Deprecated. Use "ldap_uri" instead.
.TP
.B ldapdn=\fIdn\fR
The dn where the users are stored (eg: ou=users,dc=domain,dc=com).
.TP
.B user_attr=\fIattr\fR
The LDAP attribute used to store user names (eg:cn).
.TP
.B yubi_attr=\fIattr\fR
The LDAP attribute used to store the Yubikey id.
.TP
.B yubi_attr_prefix=\fIprefix\fR
The prefix of the LDAP attribute's value, in case of a generic attribute, used to store several types of ids.
.TP
.B token_id_length=\fIlength\fR
Length of ID prefixing the OTP (this is 12 if using the YubiCloud).
.SH EXAMPLES
.RS
auth sufficient pam_yubico.so id=16 debug
.TP
auth required pam_yubico.so mode=challenge-response
.SH BUGS
Report yubico-pam bugs in
.URL "https://github.com/Yubico/yubico-pam/issues/" "the issue tracker"
.SH "SEE ALSO"
The
.URL "https://developers.yubico.com/yubico-pam/" "yubico-pam home page"
.PP
\fBykpamcfg\fR(1),
\fBpam\fR(7)
.PP
YubiKeys can be obtained from
.URL "https://www.yubico.com/" "Yubico" "."

91
pam_yubico.8.txt Normal file
View File

@ -0,0 +1,91 @@
PAM_YUBICO(8)
=============
:doctype: manpage
:man source: yubico-pam
:man manual: Yubico PAM Module Manual
== NAME
pam_yubico - Module for YubiKey authentication
== SYNOPSIS
*pam_yubico* [...]
== DESCRIPTION
The module is for authentication of YubiKeys, either with online validation of OTP, or offline validation with HMAC-SHA1 challenge-response.
== OPTIONS
*debug*::
Turns on debugging to STDOUT
*mode=*[_client_|_challenge-response_]
Set the mode of operation, client for OTP validation and challenge-response for challenge-response validation, client is the default.
*authfile*=_file_::
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.
*id*=_id_::
Set to your client identity.
*key*=_key_::
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/
*alwaysok*::
Set to enable all authentication attempts to succeed (aka presentation mode).
*try_first_pass*::
Before prompting the user for their password, the module first tries the previous stacked module´s password in case that satisfies this module as well.
*use_first_pass*::
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.
*urllist*=_list_::
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
*url*=_url_::
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
*capath*=_path_::
Specify the path where X509 certificates are stored. This is required if 'https' or 'ldaps' are used in 'url' and 'ldap_uri' respectively.
*verbose_otp*::
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. For example, OpenSSH requires you to configure "ChallengeResponseAuthentication no".
*ldap_uri*=_uri_::
Specify the LDAP server URI (e.g. ldap://localhost).
*ldap_server*=_server_::
Specify the LDAP server host (default LDAP port is used). *Deprecated. Use "ldap_uri" instead.*
*ldapdn*=_dn_::
The dn where the users are stored (eg: ou=users,dc=domain,dc=com).
*user_attr*=_attr_::
The LDAP attribute used to store user names (eg:cn).
*yubi_attr*=_attr_::
The LDAP attribute used to store the Yubikey id.
*yubi_attr_prefix*=_prefix_::
The prefix of the LDAP attribute's value, in case of a generic attribute, used to store several types of ids.
*token_id_length*=_length_::
Length of ID prefixing the OTP (this is 12 if using the YubiCloud).
== EXAMPLES
auth sufficient pam_yubico.so id=16 debug
auth required pam_yubico.so mode=challenge-response
== BUGS
Report yubico-pam bugs in the issue tracker: https://github.com/Yubico/yubico-pam/issues
== SEE ALSO
*ykpamcfg*(1), *pam*(7)
The yubico-pam home page: https://developers.yubico.com/yubico-pam/
YubiKeys can be obtained from Yubico: http://www.yubico.com/

122
ykpamcfg.1
View File

@ -1,122 +0,0 @@
.\" Copyright (c) 2011-2014 Yubico AB
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\"
.\" * Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\"
.\" * Redistributions in binary form must reproduce the above
.\" copyright notice, this list of conditions and the following
.\" disclaimer in the documentation and/or other materials provided
.\" with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" The following commands are required for all man pages.
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH ykpamcfg "1" "March 2011" "yubico-pam"
.SH NAME
ykpamcfg - Manage user settings for the Yubico PAM module.
.SH SYNOPSIS
.B ykpamcfg
[\fI-1\fR | \fI-2\fR] [\fI-A\fR] [\fI-p\fR] [\fI-i\fR] [\fI-v\fR] [\fI-h\fR]
.\" .SH DESCRIPTION
.\" Add any additional description here
.SH OPTIONS
.PP
.TP
\fB\-1\fR
use slot 1. This is the default.
.TP
\fB\-2\fR
use slot 2.
.TP
\fB\-A \fIaction\fR
choose action to perform. See ACTIONS below.
.TP
\fB\-p \fIpath\fR
specify output file for, default is ~/.yubico/challenge
.TP
\fB\-i \fIiterations\fR
number of iterations to use for pbkdf2 of expected response
.TP
\fB\-v\fR
enable verbose mode.
.SH ACTIONS
.TP
\fBadd_hmac_chalresp\fR
The PAM module can utilize the HMAC-SHA1 Challenge-Response mode found in YubiKeys
starting with version 2.2 for \fBoffline authentication\fR. This action creates the initial state
information with the C/R to be issued at the next logon.
The utility currently outputs the state information to a file in the current user's
home directory (\fI~/.yubico/challenge-123456\fR for a YubiKey with serial number API readout
enabled, and \fI~/.yubico/challenge\fR for one without).
The PAM module supports a system wide directory for these state files (in case the user's
home directories are encrypted), but in a system wide directory, the 'challenge' part should
be replaced with the username. Example : \fI/var/yubico/challenges/alice-123456\fR.
To use the system-wide mode, you currently have to move the generated state files manually and
configure the PAM module accordingly.
.SH EXAMPLE
First, program a YubiKey for challenge response on Slot 2 :
.HP
.nf
$ \fBykpersonalize \-2 \-ochal-resp \-ochal-hmac \-ohmac-lt64 \-oserial-api-visible\fR
...
Commit? (y/n) [n]: y
$
.fi
.HP
Now, set the current user to require this YubiKey for logon :
.HP
.nf
$ \fBykpamcfg \-2 \-v\fR
...
Stored initial challenge and expected response in '/home/alice/.yubico/challenge-123456'.
$
.fi
.HP
Then, configure authentication with PAM for example like this (\fImake a backup first\fR) :
.HP
\fI/etc/pam.d/common-auth\fR (from Ubuntu 10.10) :
.nf
auth required pam_unix.so nullok_secure try_first_pass
auth [success=1 new_authtok_reqd=ok ignore=ignore default=die] pam_yubico.so mode=challenge-response
auth requisite pam_deny.so
auth required pam_permit.so
auth optional pam_ecryptfs.so unwrap
.fi
.SH BUGS
Report ykpamcfg bugs in
.URL "https://github.com/Yubico/yubico-pam/issues" "the issue tracker"
.SH "SEE ALSO"
The
.URL "https://developers.yubico.com/yubico-pam/" "yubico-pam home page"
.PP
\fBpam_yubico\fR(8)
.PP
YubiKeys can be obtained from
.URL "https://www.yubico.com/" "Yubico" "."

74
ykpamcfg.1.txt Normal file
View File

@ -0,0 +1,74 @@
YKPAMCFG(1)
=========
:doctype: manpage
:man source: yubico-pam
:man manual: Yubico PAM Module Manual
== NAME
ykpamcfg - Manage user settings for the Yubico PAM module
== SYNOPSIS
*ykmapcfg* [-1 | -2] [-A] [-p] [-i] [-v] [-h]
== OPTIONS
*-1*::
use slot 1. This is the default.
*-2*::
use slot 2.
*-A* _action_::
choose action to perform. See ACTIONS below.
*-p* _path_::
specify output file for, default is ~/.yubico/challenge
*-i* _iterations_::
number of iterations to use for pbkdf2 of expected response
*-v*::
enable verbose mode.
== ACTIONS
=== add_hmac_chalresp
The PAM module can utilize the HMAC-SHA1 Challenge-Response mode found in YubiKeys starting with version 2.2 for *offline authentication*. This action creates the initial state information with the C/R to be issued at the next logon.
The utility currently outputs the state information to a file in the current user's home directory (_\~/.yubico/challenge-123456_ for a YubiKey with serial number API readout enabled, and _~/.yubico/challenge_ for one without).
The PAM module supports a system wide directory for these state files (in case the user's home directories are encrypted), but in a system wide directory, the 'challenge' part should be replaced with the username. Example : _/var/yubico/challenges/alice-123456_.
To use the system-wide mode, you currently have to move the generated state files manually and configure the PAM module accordingly.
== EXAMPLES
First, program a YubiKey for challenge response on Slot 2 :
$ ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible
...
Commit? (y/n) [n]: y
Now, set the current user to require this YubiKey for logon :
$ ykpamcfg -2 -v
...
Stored initial challenge and expected response in '/home/alice/.yubico/challenge-123456'.
Then, configure authentication with PAM for example like this (_make a backup first_) :
_/etc/pam.d/common-auth_ (from Ubuntu 10.10) :
auth required pam_unix.so nullok_secure try_first_pass
auth [success=1 new_authtok_reqd=ok ignore=ignore default=die] pam_yubico.so mode=challenge-response
auth requisite pam_deny.so
auth required pam_permit.so
auth optional pam_ecryptfs.so unwrap
== BUGS
Report ykpamcfg bugs in the issue tracker: https://github.com/Yubico/yubico-pam/issues
== SEE ALSO
*pam_yubico*(8)
The yubico-pam home page: https://developers.yubico.com/yubico-pam/
YubiKeys can be obtained from Yubico: http://www.yubico.com/