Skip to content

Commit

Permalink
Merge branch 'pr-152'
Browse files Browse the repository at this point in the history
  • Loading branch information
@klali
klali committed May 2, 2018
2 parents b86e9a2 + 3ecd8ce commit 067d451
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 38 deletions.
46 changes: 23 additions & 23 deletions pam_yubico.8.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,70 +18,70 @@ The module is for authentication of YubiKeys, either with online validation of O
Turns on debugging.

*debug_file*=_file_::
File name to write debug to, the file must exist and be a regular file. Defaults to stdout.
File name to write debug to, the file must exist and be a regular file. Defaults 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.
Mode of operation, client for OTP validation and challenge-response for challenge-response validation. Defaults to client.

*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.
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.
Your API client identity for the validation server.

*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/
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).
Succeed with all authentication attempts (*dangerous*, 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.
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.

*nullok*::
If set, don’t 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.
Don’t 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.

*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
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.
The path where X509 certificates are stored. This is required if 'https' or 'ldaps' are used in 'url' and 'ldap_uri', respectively.

*cainfo*=_file_::
Option to allow usage of a CA bundle instead of path.
Option to allow for usage of a CA bundle instead of path.

*proxy*=_proxy_::
Specify a 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. E.g. socks5h://user:pass@10.10.0.1:1080
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

*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. This option can not be used with OpenSSH.
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.

*ldap_uri*=_uri_::
Specify the LDAP server URI (e.g. ldap://localhost).
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.*
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). If 'ldap_filter' is used this is the base from which the subtree search will be performed.
The distinguished name (DN) where the users are stored (eg: ou=users,dc=domain,dc=com). If 'ldap_filter' is used this is the base from which the subtree search will be performed.

*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.
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.
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).
Expand All @@ -93,13 +93,13 @@ The user to attempt a LDAP bind as.
The password to use on LDAP bind.

*ldap_filter*=_filter_::
An ldap filter to use for attempting to find the correct object in LDAP. In this string %u will be replaced with the username.
A LDAP filter to use for attempting to find the correct object in LDAP. In this string `%u` will be replaced with the username.

*ldap_cacertfile*=_cacertfile_::
Ca certfile for the LDAP connection.
CA certitificate file for the LDAP connection.

*chalresp_path*=_path_::
Path of a system wide directory where challenge-response files can be found for users. Default location is $HOME/.yubico/
Path of a system-wide directory where challenge-response files can be found for users. Default location is `$HOME/.yubico/`.

== EXAMPLES

Expand All @@ -112,11 +112,11 @@ Path of a system wide directory where challenge-response files can be found for
== FILES

*$HOME/.yubico/authorized_yubikeys*::
If *authfile* is not set this file is used for the mapping between YubiKey public id and in _client_ mode.
If *authfile* is not set, this file is used for the mapping between YubiKey public ID and in _client_ mode.

*$HOME/.yubico/challenge*::
*$HOME/.yubico/challenge-_serial_number_*::
If *chalresp_path* is not set these files are used to hold next challenge and expected response for the user in _challenge-response_ mode. If *chalresp_path* is set the filename will be username instead of challenge.
If *chalresp_path* is not set, these files are used to hold next challenge and expected response for the user in _challenge-response_ mode. If *chalresp_path* is set the filename will be _username_ instead of _challenge_.

== BUGS
Report yubico-pam bugs in the issue tracker: https://github.com/Yubico/yubico-pam/issues
Expand Down
30 changes: 15 additions & 15 deletions ykpamcfg.1.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,56 +12,56 @@ ykpamcfg - Manage user settings for the Yubico PAM module

== OPTIONS
*-1*::
use slot 1. This is the default.
Use slot 1. This is the default.

*-2*::
use slot 2.
Use slot 2.

*-A* _action_::
choose action to perform. See ACTIONS below.
Choose action to perform. See ACTIONS below.

*-p* _path_::
specify output file, default is ~/.yubico/challenge
Specify output file, default is `~/.yubico/challenge`.

*-i* _iterations_::
number of iterations to use for pbkdf2 of expected response
Number of iterations to use for PBKDF2 of expected response.

*-v*::
enable verbose mode.
Enable verbose mode.

*-V*::
display version and exit
Display version and exit.

*-h*::
display help and exit
Display help and exit.

== 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 PAM module can utilize the HMAC-SHA1 Challenge-response (C/R) 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 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_.
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:
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 :
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_) :
Then, configure authentication with PAM for example like this (_make a backup first_):

_/etc/pam.d/common-auth_ (from Ubuntu 10.10) :
_/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
Expand Down

0 comments on commit 067d451

Please sign in to comment.