Validation Protocol

The YubiKey Validation Protocol enables GreenRADIUS to validate YubiKey OTPs through a special endpoint without performing username/password validation nor user-YubiKey assignment validation.

Prerequisites

  • GreenRADIUS 4.4.1.1 or later
  • A valid license which supports OTPOnly functionality

Usage

The endpoint is accessible at https://<IP/hostname of GreenRADIUS>/wsapi/2.0/verify by POST or GET request.

HTTP parameters should be supplied in the usual way as "form-input" style entries, e.g.

https://<IP/hostname of GreenRADIUS>/wsapi/2.0/verify>nonce=12341234123412341234&id=1&otp=grktccrrijbribbcdtveetgbvergnrvcnkngnfljjfcj'

The following parameters are required:

  • id: The Client ID for this requestor.
  • otp: The OTP to validate
  • nonce: A unique identifier for this request. Must be between 16 and 40 characters in length.

The following parameters are optional:

  • timestamp: If 1, session counter information and timestamp will be returned with response.

The response will be returned as a series of key=value pairs, separated by newlines. The otp and nonce will be echoed back, accompanied by time stamp, session counter, and session use if timestamp was set in the request. An HMAC signature will also be returned, as the h parameter. The result will be returned in the status parameter, and takes the following possible values:

  • OK: The OTP is valid.
  • BAD_OTP: The OTP is invalid.
  • REPLAYED_OTP: The OTP has already been used in a previous request.
  • REPLAYED_REQUEST: The OTP/nonce combination has already been used in a previous request.
  • MISSING_PARAMETER: The request is lacking a required parameter.
  • NO_SUCH_CLIENT: A request ID other than 1 was selected.
  • BACKEND_ERROR An internal error has occurred. Please contact Green Rocket Security if you see this message.

Example of a request response:

h=u7EiYbXxElBBKRfkkCNCxf6zj/4=
t=2021-10-13T20:13:02Z0820
otp=grktccrrckjlbejchetblehkefgcnrtgdevvgiikkdfc
nonce=12341234123412345
timestamp=9323959
sessioncounter=2
sessionuse=0
status=OK

Editing Client Parameters

It is possible to edit some client parameters in the web administration console, such as the Client ID. To do this, log into the web admin console and navigate to Global Configuration > Client-based Authentication Policies. Select the client (OTP Only clients will be marked YUBIKEY_OTP_VALIDATION).

Client-based authentication policy configuration

Click "Edit Selected." You will then be able to edit the Client ID, description, and shared HMAC key for the client.

client-based authentication policy configuration - yubikey only

Updated 2021-11-04
© 2021 Green Rocket Security Inc. All rights reserved.