1.\" $OpenBSD: login_yubikey.8,v 1.10 2020/07/08 10:41:38 job Exp $ 2.\" 3.\" Copyright (c) 2010 Daniel Hartmeier <daniel@benzedrine.cx> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" - Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" - Redistributions in binary form must reproduce the above 13.\" copyright notice, this list of conditions and the following 14.\" disclaimer in the documentation and/or other materials provided 15.\" with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 20.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 21.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 23.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 24.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 25.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 27.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: July 8 2020 $ 31.Dt LOGIN_YUBIKEY 8 32.Os 33.Sh NAME 34.Nm login_yubikey 35.Nd provide YubiKey OTP authentication type 36.Sh SYNOPSIS 37.Nm login_yubikey 38.Op Fl dv 39.Op Fl s Ar service 40.Ar user 41.Op Ar class 42.Sh DESCRIPTION 43The 44.Nm 45utility is called by 46.Xr login 1 , 47.Xr su 1 , 48.Xr ftpd 8 , 49and others to authenticate the 50.Ar user 51with the Yubico one-time password (OTP) authentication mechanism. 52.Pp 53The options are as follows: 54.Bl -tag -width indent 55.It Fl d 56Debug mode. 57Output is sent to the standard output instead of the 58.Bx 59Authentication backchannel. 60.It Fl s Ar service 61Specify the service. 62Currently, only 63.Li challenge , 64.Li login , 65and 66.Li response 67are supported. 68The default protocol is 69.Em login . 70.It Fl v 71This option and its value are ignored. 72.El 73.Pp 74The 75.Ar user 76argument is the login name of the user to be authenticated. 77.Pp 78The optional 79.Ar class 80argument is accepted for consistency with the other login scripts but 81is not used. 82.Pp 83.Nm 84will read the user's UID (12 hex digits) from the file 85.Em user.uid , 86the user's key (32 hex digits) from 87.Em user.key , 88and the user's last-use counter from 89.Em user.ctr 90in the 91.Em /var/db/yubikey 92directory. 93.Pp 94If 95.Ar user 96does not have a UID or key, the login is rejected. 97If 98.Ar user 99does not have a last-use counter, a value of zero is used and 100any counter is accepted during the first login. 101.Pp 102The one-time password provided by the user is decrypted using the 103user's key. 104After the decryption, the checksum embedded in the one-time password 105is verified. 106If the checksum is not valid, the login is rejected. 107.Pp 108If the checksum is valid, the UID embedded in the one-time password 109is compared against the user's UID. 110If the UID does not match, the login is rejected. 111.Pp 112If the UID matches, the use counter embedded in the one-time password 113is compared to the last-use counter. 114If the counter is less than or equal to the last-use counter, the 115login is rejected. 116This indicates a replay attack. 117.Pp 118If the counter is larger than the last-use counter, the counter 119is stored as the new last-use counter, and the login is accepted. 120.Sh FILES 121.Bl -tag -width /var/db/yubikey 122.It Pa /var/db/yubikey 123Directory containing user entries for YubiKey OTP security keys. 124.El 125.Sh SEE ALSO 126.Xr login 1 , 127.Xr login.conf 5 128.Sh HISTORY 129The 130.Nm 131utility first appeared in 132.Ox 5.1 . 133.Sh AUTHORS 134.An Daniel Hartmeier 135.Sh CAVEATS 136The 137.Nm 138utility does not implement the U2F/FIDO2 open authentication standard. 139