PAM_YUBICO(8)

💖 pam_yubico — the Yubico PAM module 💖

okay bestie, welcome to pam_yubico, the module for YubiKey authentication ✨ it lives in the Yubico PAM Module Manual, section 8 of your local man pages, and it's genuinely iconic. no cap.

---

✨ SYNOPSIS ✨

pam_yubico [...]

---

🌸 DESCRIPTION 🌸

so basically this module handles authentication of YubiKeys, and it does it two whole ways:

• online validation of OTP — the OTP gets checked against a validation server
• offline validation with HMAC-SHA1 challenge-response — no internet required, just vibes and crypto 🦋

---

🎀 OPTIONS 🎀

bestie there are a LOT of these and we're going through every single one, no skipping, periodt 💅

• debug — turns on debugging. that's it. that's the option. 👑
• debug_file=file — the file name to write debug output to. heads up: the file must already exist and it must be a regular file. defaults to stdout.
• mode=[client|challenge-response] — picks the mode of operation. client = OTP validation, challenge-response = challenge-response validation. defaults to client. lowkey the main character switch of this whole page ✨
• authfile=file — where the file lives that holds the mappings of YubiKey token IDs to user names. the format is:

username:first_public_id:second_public_id:...

default location is $HOME/.yubico/authorized_yubikeys.

• id=id — your API client identity for the validation server. iykyk.
• key=key — your client key, in base64 format. the client key is also known as the API key, and it's what provides integrity in the communication between you (the client) and the validation server. if you want one for use with the default YubiCloud service, please go to: https://upgrade.yubico.com/getapikey/ 🫶
• alwaysok — succeed with all authentication attempts. > this one is dangerous. it's presentation mode, bestie. do not ship this to prod. 💀
• try_first_pass — before it prompts 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 — forces the module to use a previous stacked module's password and will never prompt the user. if no password is available, or the password is not appropriate, the user gets denied access. no retries, no mercy 😭
• always_prompt — if set, don't attempt to do a lookup to determine whether the user has a YubiKey configured; 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's password (in a YubiKey+OTP auth scenario).
• nullok — don't fail when there are no tokens declared for the user in the authorization mapping files or in LDAP. you can use this to make YubiKey authentication optional, unless the user has associated tokens. very "it's fine either way" energy 🌈
• ldap_starttls — if set, issue a STARTTLS command to the LDAP connection before attempting to bind to it. super common setup for servers that only listen on port 389 but still require TLS.
• ldap_bind_as_user — use the user logging in to bind to LDAP. this uses the password the user provided 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.
• urllist=list — a 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 — > bestie, this option should not be used, please use the urllist option instead. it sets the URL template to use, 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 — the path where X509 certificates are stored. this is required if https or ldaps are used in url and ldap_uri, respectively. don't forget it, she's important 🎀
• cainfo=file — option to allow for usage of a CA bundle instead of a path.
• proxy=proxy — 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 — 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 — the LDAP server URI (e.g. ldap://localhost).
• ldap_server=server — the LDAP server host (default LDAP port is used). > deprecated. use ldap_uri instead, she's the upgraded version 💅
• ldapdn=dn — 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.
• ldap_clientcertfile=clientcertfile — the path to a client cert file to use when talking to the LDAP server. note this requires ldap_clientkeyfile to be set as well. they're a package deal 🫶
• ldap_clientkeyfile=clientkeyfile — the path to a key to be used with the client cert when talking to the LDAP server. note this requires ldap_clientcertfile to be set as well. yeah, same deal, other direction.
• 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 the ID prefixing the OTP (this is 12 if using the YubiCloud).
• ldap_bind_user=user — the user to attempt a LDAP bind as.
• ldap_bind_password=password — the password to use on LDAP bind.
• ldap_filter=filter — 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 certitificate file for the LDAP connection. (yes, that's exactly how the original spells it, and yes, i'm keeping it, we don't erase history here 😌)
• chalresp_path=path — path of a system-wide directory where challenge-response files can be found for users. default location is $HOME/.yubico/.
• mysql_server=mysqlserver — hostname/adress of mysql server. example 10.0.0.1.
• mysql_port=mysqlport — network port of mysql server.
• mysql_user=mysqluser — user for accessing to the database. > strongly recommended to use a specific user with read only access. protect yourself, bestie 🔥
• mysql_password=mysqlpassword — mysql password associated to the user.
• mysql_database=mysqldatabase — the name of the database. example: otp

---

⭐ EXAMPLES ⭐

here's the tea, straight from the source:

auth sufficient pam_yubico.so id=16 debug

auth required pam_yubico.so mode=challenge-response

auth required pam_yubico.so id=16 ldap_uri=ldaps://ldap.example.com ldap_filter=(uid=%u) yubi_attr=yubiKeyId

---

🦋 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.
• $HOME/.yubico/challenge, $HOME/.yubico/challenge-serial_number — if chalresp_path is not set, these files are used to hold the next challenge and the expected response for the user in challenge-response mode. if chalresp_path is set, the filename will be username instead of challenge.

---

🙈 BUGS 🙈

found a bug? report yubico-pam bugs in the issue tracker: https://github.com/Yubico/yubico-pam/issues — the maintainers will love you for it, fr fr 💜

---

👑 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/ 🎀

---

okay bestie that's the whole page, and you ate it 💅 this was yubico-pam, Version 2.27, living in section 8 of the manual, PAM_YUBICO(8). go forth and authenticate, no cap 🌸🫶