Verify

{note} yubikey-u2f has been archived and is no longer maintained. Use caution when installing in your apps.

• Introduction
• Verify To Associate
• Verify To Authenticate

#Introduction

Most usage of this package will be through the \Rawilk\Yubikey\Facades\Yubikey facade, which represents the \Rawilk\Yubikey\Yubikey class. You will need to use the facade to associate a new security key with a user, and you may optionally use it to verify a security key for a user, but our trait for the user model will make doing that a little easier.

#Verify To Associate

To verify a security key, you will need to capture the OTP token generated by the security key when the user touches the key to confirm they want to use it. In this example, we will reference it from a POST variable in the request via request()->otp, but your implementation may be different.

$response = \Rawilk\Yubikey\Facades\Yubikey::verify(request()->otp);

Auth::user()->associateYubikeyIdentity($response['identity']);

Given that the security key signature is valid, and the user doesn't already have that key tied to their account, this will associate that security key with the user account. The $response variable will be an array returned from the Yubico API only if the request was for a valid key. In all other cases, a \Rawilk\Yubikey\Exceptions\YubikeyVerifyException will be thrown. The following scenarios will result in an exception being thrown:

Status	Description
BAD_OTP	The OTP is an invalid format.
REPLAYED_OTP	The OTP has already been seen by the service.
BAD_SIGNATURE	The HMAC signature verification failed.
MISSING_PARAMETER	The request lacks a required parameter.
NO_SUCH_CLIENT	The request client id is not valid.
OPERATION_NOT_ALLOWED	The API key is not allowed to verify OTPs.
BACKEND_ERROR	Unexpected error occured on a Yubico server.
NOT_ENOUGH_ANSWERS	A Yubico server could not get requested number of syncs before timeout.
REPLAYED_REQUEST	The Yubico server has already seen the OTP/Nonce combination before.

When associating a security key to a user via associateYubikeyIdentity, a \Rawilk\Yubikey\Exceptions\YubikeyIdentityException will be thrown if:

• The user (or another user) already registered the security key.
• The user already has 5 keys registered to their account.

{tip} You may specify a name for the security key as the second argument for the associateYubikeyIdentity() method. This can be useful for users to keep track of which keys are which.

#Verify To Authenticate

In your authentication workflows, you may verify that a security key as a two-factor authentication method for a user via the verifyYubikeyIdentity() method provided on the HasYubikeys trait.

$verified = $user->verifyYubikeyIdentity(request()->otp);

Behind the scenes, the verifyYubikeyIdentity method is calling \Rawilk\Yubikey\Facades\Yubikey::verify() to verify the legitimacy of the security key, and is then checking that the security key is registered and belongs to the given user. As with the previous step for associating the key, a \Rawilk\Yubikey\Exceptions\YubikeyVerifyException may be thrown for any number of reasons if the request fails, and your application should handle them accordingly.

You may choose to call the verify method on the facade yourself, but you must then ensure the security key is actually for the user you're trying to authenticate.