diff --git a/README b/README index b9b7483..b042f5d 100644 --- a/README +++ b/README @@ -134,97 +134,102 @@ For more information, see the project Wiki page. Supported PAM module parameters are: ------- - "authfile": to indicate the location of the file that holds the - mappings of Yubikey token IDs to user names. +authfile:: +To indicate the location of the file that holds the +mappings of Yubikey token IDs to user names. - "id": to indicate your client identity. +id:: To indicate your client identity. - "key": to indicate 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 : +key:: +To indicate 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, go https://upgrade.yubico.com/getapikey[here]. - https://upgrade.yubico.com/getapikey/ +debug:: to enable debug output to stdout. - "debug": to enable debug output to stdout. +alwaysok:: +to enable all authentication attempts to succeed +(aka presentation mode). - "alwaysok": 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. - "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. - "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 of URL templates to be used. This is set by calling +ykclient_set_url_bases. The list should be in the format : +`https://server/wsapi/2.0/verify;https://server/wsapi/2.0/verify` - "urllist": List of URL templates to be used. This is set by calling - ykclient_set_url_bases. The list should be in the format : +url:: +This option should not be used, please use the urllist +option instead. +Specify the URL template to use, this is set by calling +yubikey_client_set_url_template, which defaults to: - "https://server/wsapi/2.0/verify;https://server/wsapi/2.0/verify" + https://api.yubico.com/wsapi/verify?id=%d&otp=%s - "url": This option should not be used, please use the urllist - option instead. - Specify the URL template to use, this is set by calling - yubikey_client_set_url_template, which defaults to: +or - https://api.yubico.com/wsapi/verify?id=%d&otp=%s + https://api.yubico.com/wsapi/2.0/verify?id=%d&otp=%s - or +depending on your version of yubico-c-client. - https://api.yubico.com/wsapi/2.0/verify?id=%d&otp=%s +capath:: +specify the path where X509 certificates are stored. This is +required if 'https' or 'ldaps' are used in 'url' and 'ldap_uri' +respectively. - depending on your version of yubico-c-client. +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. - "capath": specify the path where X509 certificates are stored. This is - required if 'https' or 'ldaps' are used in 'url' and 'ldap_uri' - respectively. +This requires the service using the PAM module to +display custom fields. For example, OpenSSH requires +you to configure `ChallengeResponseAuthentication no`. - "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": specify the LDAP server URI (e.g. ldap://localhost). +ldap_uri:: specify the LDAP server URI (e.g. ldap://localhost). - "ldapserver": specify the LDAP server host (default LDAP port is used). - _Deprecated. Use "ldap_uri" instead._ +ldapserver:: +specify the LDAP server host (default LDAP port is used). +_Deprecated. Use "ldap_uri" instead._ - "ldapdn": specify the dn where the users are stored - (eg: ou=users,dc=domain,dc=com). +ldapdn:: +specify the dn where the users are stored +(eg: ou=users,dc=domain,dc=com). - "user_attr": specify the LDAP attribute used to store user names (eg:cn). +user_attr:: specify the LDAP attribute used to store user names (eg:cn). - "yubi_attr": specify the LDAP attribute used to store the Yubikey id. +yubi_attr:: specify the LDAP attribute used to store the Yubikey ID. - "yubi_attr_prefix": - specify the prefix of the LDAP attribute's value, in case - of a generic attribute, used to store several types of ids. +yubi_attr_prefix:: +specify 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 of ID prefixing the OTP (this is 12 if using the - YubiCloud). - "mode": - Mode of operation. Use "client" for online validation with - a YubiKey validation service such as the YubiCloud, or use - "challenge-response" for offline validation using YubiKeys - with HMAC-SHA-1 Challenge-Response configurations. See the - man-page ykpamcfg(1) for further details on how to configure - offline Challenge-Response validation. +token_id_length:: +Length of ID prefixing the OTP (this is 12 if using the +YubiCloud). + +mode:: +Mode of operation. Use "client" for online validation with +a YubiKey validation service such as the YubiCloud, or use +"challenge-response" for offline validation using YubiKeys +with HMAC-SHA-1 Challenge-Response configurations. See the +man-page ykpamcfg(1) for further details on how to configure +offline Challenge-Response validation. ------ @@ -250,7 +255,7 @@ be used. Central authorization mapping ----------------------------- -Create a /etc/yubikey_mappings, the file must contain a user name and the +Create a `/etc/yubikey_mappings`, the file must contain a user name and the Yubikey token ID separated by colons (same format as the passwd file) for each user you want to allow onto the system using a Yubikey. @@ -287,10 +292,8 @@ Obtaining the Yubikey token ID (a.k.a. public ID) You can obtain the Yubikey token ID in several ways. One is by removing the last 32 characters of any OTP (One Time Password) -generated with your Yubikey. Another is by using the modhex -calculator located here: - -http://demo.yubico.com/php-yubico/Modhex_Calculator.php +generated with your Yubikey. Another is by using the +http://demo.yubico.com/php-yubico/Modhex_Calculator.php[modhex calculator]. Enter your Yubikey OTP and convert it, your Yubikey token ID is 12 characters and listed as: @@ -307,7 +310,7 @@ Fast way It will output an OTP into the shell: ------ - $ cccccccgklgcvnkcvnnegrnhgrjkhlkfhdkclfncvlgj + $ cccccccgklgcvnkcvnnegrnhgrjkhlkfhdkclfncvlgj bash: cccccccgklgcvnkcvnnegrnhgrjkhlkfhdkclfncvlgj: command not found ------ @@ -348,16 +351,7 @@ Examples -------- If you want to use the Yubikey to authenticate you on linux console -logins, add the following to the top of /etc/pam.d/login: +logins, add the following to the top of `/etc/pam.d/login`: ------- - auth sufficient pam_yubico.so id=16 debug ------- - - -Feedback --------- - -If you want to discuss anything related to the Yubico PAM module, -please e-mail the mailing list yubico-devel@googlegroups.com. + auth sufficient pam_yubico.so id=16 debug