Yubikey Module
The yubikey module decrypts and validates Yubikey static and
dynamic One-Time Password (OTP) tokens.
For more information about Yubikey, please see:
Configuration Settings
- id_length
-
The length (number of ASCII bytes) of the Public-ID portion of the OTP string.
Yubikey defaults to a 6 byte ID (2 * 6 = 12)
- split
-
If true, the authorize method of
rlm_yubikeywill attempt to split the value ofUser-Password, into the user’s password, and the OTP token.
If enabled and successful, the value of &request.User-Password will be
truncated and &request.Vendor-Specific.Yubicon.Yubikey-OTP will be added.
|
- decrypt
-
Whether tokens will be decrypted and processed locally.
In the authorize section, this module should be placed before the
persistent storage module.
The authenticate section should have the following added:
Auth-Type yubikey {
#pap
yubikey
}If two factor authentication (password concatenated with OTP) is required, split configuration should be set to yes and the pap module should be uncommented.
Each account will need a password added (either using attribute Password.Cleartext,
SSHA-Password, etc.).
The module itself does not provide persistent storage as this would duplicate functionality already in the server.
Yubikey authentication needs two attributes retrieved from persistent storage:
| Attributes | Description |
|---|---|
|
The AES key used to decrypt the OTP data.
The |
|
This is compared with the counter in the OTP data and used to prevent replay attacks. This attribute will also be available in the request list after successful decryption. |
Vendor-Specific.Yubicon.Yubikey-Counter isn’t strictly required, but the server will generate
warnings if it’s not present when yubikey.authenticate is called.
|
These attributes are available after authorization:
| Attributes | Description |
|---|---|
|
The public portion of the OTP string.
The value is a |
and additionally if 'split' is set:
| Attributes | Description |
|---|---|
|
The OTP portion of |
These attributes are available after authentication (if successful):
| Attributes | Description |
|---|---|
|
The encrypted ID included in OTP data,
should be verified for increased security.
The value is a |
|
The last counter value (should be recorded).
The value is a concatenation of the 16-bit
session count & |
|
Token’s internal clock (mainly useful for debugging).
The value is a 24-bit increasing |
|
Randomly generated value from the token. The value is a 16-bit integer. |
- validate
-
Validation mode - Tokens will be validated against a Yubicloud server.
- validation { … }
-
Settings for validation mode.
- servers { … }
-
URL of validation server, multiple URL config items may be used to list multiple servers.
| Option | Description |
|---|---|
|
Placeholder for public ID of the token. |
|
Placeholder for the token string itself. |
| If no URLs are listed, will default to the default URLs in the ykclient library, which point to the yubico validation servers. |
- client_id
-
API Client ID.
Must be set to your client id for the validation server.
- api_key
-
API Secret key (Base64 encoded).
Must be set to your API key for the validation server.
- pool { … }
-
Connection pool parameters.
- start
-
Connections to create during module instantiation.
If the server cannot create specified number of
connections during instantiation it will exit.
Set to 0 to allow the server to start without the
external service being available.
- min
-
Minimum number of connections to keep open.
- max
-
Maximum number of connections.
If these connections are all in use and a new one is requested, the request will NOT get a connection.
Setting max to LESS than the number of threads means
that some threads may starve, and you will see errors
like No connections available and at max connection limit.
Setting max to MORE than the number of threads means
that there are more connections than necessary.
If max is not specified, then it defaults to the number
of workers configured.
- uses
-
Number of uses before the connection is closed.
| A setting of 0 means infinite (no limit). |
- retry_delay
-
The number of seconds to wait after the server tries to open a connection, and fails.
During this time, no new connections will be opened.
- lifetime
-
The lifetime (in seconds) of the connection.
| A setting of 0 means infinite (no limit). |
- idle_timeout
-
The idle timeout (in seconds).
A connection which is unused for this length of time will be closed.
| A setting of 0 means infinite (no timeout). |
- spread
-
Enable LRU (Least Recently Used).
The yubico library uses curl multi-handles. If the multi-handle is reused
before all requests are completed the connections are re-established.
The cost of re-establishing the connections is greater than the benefit of maintaining a small pool of connections or optimising for link latency.
|
All configuration settings are enforced. If a connection is closed because of
When that happens, it will open a new connection. It will also log a WARNING message. The solution is to either lower the "min" connections, or increase lifetime/idle_timeout. |
Default Configuration
# https://www.yubico.com/
yubikey {
# id_length = 12
# split = yes
decrypt = no
validate = no
validation {
servers {
# uri = 'http://api.yubico.com/wsapi/2.0/verify?id=%d&otp=%s'
# uri = 'http://api2.yubico.com/wsapi/2.0/verify?id=%d&otp=%s'
}
# client_id = 00000
# api_key = '000000000000000000000000'
pool {
start = 0
min = 0
# max =
uses = 0
retry_delay = 30
lifetime = 86400
idle_timeout = 60
spread = yes
}
}
}