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=99999&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: The Client ID does not exist in GreenRADIUS.
• 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

Adding a Client

To add a client in GreenRADIUS, click on the Global Configuration tab, then click Client-based Authentication Policies. Then click the "Add a New Client" button.

You will then be able to add the Client ID, description, and shared HMAC key for the client. (Client ID "1" is reserved for internal purposes and must not be used.)